# 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`
```python
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. 상태 확인
```bash
# Passport 상태 확인
curl "http://localhost:9000/auth/naverworks/passport/status?user_id=heejae"
```

### 2. OAuth 플로우 테스트
```bash
# 1. 브라우저에서 OAuth 시작
https://auth.ro-being.com/auth/naverworks/passport/install?user_id={user_id}

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

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

### 3. Docker 로그 확인
```bash
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 저장 기능 추가