DOCS/journey/troubleshooting/250917_네이버웍스_passport_작업.md

NAVER WORKS Passport 구현 작업 (2025-09-17)

작업 개요

NAVER WORKS OAuth 2.0 기반 Passport 시스템 구현 완료. Gmail/Slack 패턴을 참조하여 NAVER WORKS API 접근 권한 관리 시스템 구축.

구현 완료 사항

1. 파일 생성

위치: /home/admin/auth-server/app/providers/naverworks_passport.py

구현 기능:

• OAuth 2.0 인증 플로우
• OIDC userinfo 조회
• PostgreSQL 토큰 저장/관리
• Refresh Token Rotation 대비

주요 엔드포인트:

• GET /auth/naverworks/passport/install?user_id={user_id}&return_url={url}

  • OAuth 인증 시작
  • state에 user_id 포함하여 CSRF 방지

• GET /auth/naverworks/passport/callback?code={code}&state={state}

  • Authorization code → Access token 교환
  • OIDC userinfo 조회
  • DB에 토큰 정보 저장 (UPSERT)

• GET /auth/naverworks/passport/status?user_id={user_id}

  • 패스포트 보유 여부 확인
  • 토큰 만료 상태 체크
  • capabilities 반환

2. 라우터 등록

파일: /home/admin/auth-server/app/main.py

from app.providers import naverworks_passport
app.include_router(naverworks_passport.router, prefix="/auth/naverworks/passport", tags=["NAVER WORKS Passport"])

2-1. 일반 로그인 시 토큰 저장 (✅ 2025-09-18 추가)

파일: /home/admin/auth-server/app/providers/naverworks.py

구현 내용:

• 일반 OAuth 로그인(/auth/naverworks/callback)에서도 토큰 DB 저장
• access_token, refresh_token, id_token 모두 naverworks_token 테이블에 저장
• 로그인 시 is_equipped=false로 설정 (Passport 설치 시 true)
• 토큰 저장 실패해도 로그인은 계속 진행

3. DB 스키마 (실제 확인)

테이블명: naverworks_token

컬럼명	타입	설명
id	UUID (PK)	gen_random_uuid()
user_id	UUID	user 테이블 FK
username	VARCHAR(255)	빠른 조회용
domain_id	VARCHAR(255)	NAVER WORKS 도메인 ID
account_id	VARCHAR(255)	NAVER WORKS 계정 ID
access_token	TEXT	확인 필요: 사용 여부
refresh_token	TEXT	확인 필요: 사용 여부
token_type	VARCHAR(50)	기본값: 'Bearer'
token_data	JSONB	access_token, refresh_token 저장
oauth_config	JSONB	client_id, client_secret
scopes	JSONB	권한 목록
metadata	JSONB	email, name, org_name 등
expires_at	TIMESTAMP	확인 필요: expiry와 중복?
expiry	TIMESTAMP	확인 필요: expires_at와 중복?
service_account	VARCHAR(255)	Service Account ID
is_equipped	BOOLEAN	기본값: false
created_at	TIMESTAMPTZ	생성 시각
updated_at	TIMESTAMPTZ	수정 시각

인덱스:

• PRIMARY KEY: id
• idx_naverworks_token_user_id
• idx_naverworks_token_expires_at

4. 환경변수 설정

환경변수 (확인 완료)

• NAVER_WORKS_CLIENT_ID
• NAVER_WORKS_CLIENT_SECRET
• NAVER_WORKS_REDIRECT_URI
• NAVER_WORKS_SERVICE_ACCOUNT
• NAVER_WORKS_TENANT_ID
• NAVER_WORKS_PRIVATE_KEY_BASE64
• NAVER_WORKS_SCOPES
• NAVER_WORKS_PASSPORT_REDIRECT_URI

⚠️ 확인 필요 사항

1. NAVER WORKS Developer Console 설정 확인

작업 필요: NAVER WORKS Developer Console 접속하여 실제 Redirect URL 확인

• 경로: Developers > Apps > Ro-being > OAuth > Redirect URL
• 현재 가정: https://auth.ro-being.com/auth/naverworks/passport/callback
• 실제 설정값과 다를 경우 .env 파일 수정 필요

2. Private Key 처리

• 현재 Base64 인코딩된 형태로 환경변수에 저장
• Git에는 절대 포함하지 않도록 주의
• 보안을 위해 Vault 등 암호화된 저장소 사용 권장

테스트 방법

1. 상태 확인

# Passport 상태 확인
curl "http://localhost:9000/auth/naverworks/passport/status?user_id=heejae"

2. OAuth 플로우 테스트

# 1. 브라우저에서 OAuth 시작
https://auth.ro-being.com/auth/naverworks/passport/install?user_id={user_id}

# 2. NAVER WORKS 로그인 및 권한 승인

# 3. 콜백 처리 후 리다이렉트
# return_url 또는 기본 페이지로 이동

3. Docker 로그 확인

docker logs auth-server --tail 50 | grep naverworks

다음 단계

Phase 2: Skill 서비스 구현

1. skill-naverworks 서비스 생성 (포트 8511)

   • 캘린더 API 연동
   • 메일 발송 기능
   • 주소록 관리

2. 토큰 자동 갱신 로직

   • Refresh Token Rotation 처리
   • 만료 전 자동 갱신

3. Frontend 통합

   • 로그인 버튼 추가
   • Skills Panel에 NAVER WORKS 아이템 추가

Phase 3: Service Account 활용

1. 조직 전체 데이터 접근

   • JWT 기반 Service Account 인증
   • 배치 작업용 토큰 관리

2. 주기적 동기화

   • 조직 캘린더 동기화
   • 사용자 정보 업데이트

주의사항

1. Refresh Token Rotation

   • NAVER WORKS는 refresh_token 사용 시 새로운 토큰 발급
   • 기존 refresh_token은 즉시 무효화
   • DB 동기화 매우 중요

2. 스코프 관리

   • 현재 설정: openid, profile, email, calendar, contact, mail, task, user, file
   • 실제 사용 시 최소 권한 원칙 적용 권장

3. 에러 처리

   • OAuth 에러 코드 적절히 처리
   • 토큰 만료 시 자동 갱신 또는 재인증 유도

참고 자료

• NAVER WORKS Developers: https://developers.worksmobile.com
• OAuth 2.0 가이드: https://developers.worksmobile.com/kr/docs/auth
• API 레퍼런스: https://developers.worksmobile.com/kr/reference

작동 확인 (2025-09-18 00:56)

• 로그인: ✅ 정상 작동 (302 리다이렉트)
• 패스포트 설치: ✅ 정상 작동 (307 리다이렉트)
• 토큰 DB 저장: ✅ 로그인 시 자동 저장 확인
• 테이블 레코드: 사용자별 토큰 정상 저장 확인

작업자

• 작성일: 2025-09-17
• 작성자: Claude (51123 서버 관리자)
• 검토 필요: NAVER WORKS Developer Console Redirect URL 확인

수정 이력

• 2025-09-18: 테이블명 수정 (naverworks_tokens → naverworks_token)
• 2025-09-18: 일반 로그인 시에도 토큰 DB 저장 기능 추가