DOCS/ideas/250916_네이버웍스_캘린더_API_연동_가이드.md

네이버웍스 API 연동 가이드

[현재 프로젝트 상태] 네이버웍스 API 연동 미구현 (OAuth2 토큰 관리 로직 없음, 관련 skill 서비스 미존재, auth-server에 Works API 인증 미탑재).

구현 현황 및 필요 작업

현재 상태

• auth-server: NAVER WORKS OAuth 미구현 (Gmail, Slack만 존재)
• skill 서비스: NAVER WORKS 전용 스킬 없음
• nginx: NAVER WORKS 라우팅 설정 없음

확인된 NAVER WORKS OAuth 2.0 엔드포인트

• Authorization: https://auth.worksmobile.com/oauth2/v2.0/authorize
• Token: https://auth.worksmobile.com/oauth2/v2.0/token
• Userinfo (OIDC): https://www.worksapis.com/v1.0/oidc/userinfo
• API Base: https://www.worksapis.com/v1.0/

---

1. 로빙(RO-BEING) 앱 설정 현황

• 앱 이름: Ro-being
• 소속: company-x.partners (155032)

1.1. 인증 정보

• Client ID: [환경변수 NAVERWORKS_CLIENT_ID 참조]
• Client Secret: [환경변수 NAVERWORKS_CLIENT_SECRET 참조]

  • ⚠️ 경고: 이 값은 외부에 노출되어서는 안 되며, Git 등 버전 관리 시스템에 포함하지 마십시오. Vault 또는 암호화된 환경 변수를 통해 안전하게 관리해야 합니다.

• Service Account: [환경변수 NAVERWORKS_SERVICE_ACCOUNT 참조]

1.2. 토큰 설정

• Access Token 유효기간: 1시간
• Refresh Token Rotation: On (보안 강화)

1.3. OAuth 설정

• Redirect URL: https://auth.robeing.com/oauth/naverworks/callback
• 활성화된 Scopes:
  • openid, profile, email (OIDC 사용자 식별용)
  • calendar (캘린더 읽기/쓰기)
  • contact (주소록 읽기/쓰기)
  • file (드라이브 파일 접근)
  • mail (메일 읽기/보내기)
  • task (업무 관리)
  • user (조직 내 사용자 정보 조회)

---

2. 인증 방식

네이버웍스 API를 사용하기 위해서는 먼저 Access Token을 발급받아야 합니다. 현재 앱 설정에 따라 아래 두 가지 방식 모두 사용 가능합니다.

1. 구성원 계정으로 인증 (OAuth 2.0 / OIDC): 사용자가 직접 로그인하여 자신의 데이터에 대한 접근을 허용하는 방식입니다. (예: "내 캘린더 일정 조회")
2. 서비스 계정으로 인증 (JWT): 사용자 로그인 없이, 시스템(로빙)이 조직 전체의 데이터에 접근할 때 사용합니다. (예: 주기적인 데이터 동기화)

3. API 사용 예시 및 주요 엔드포인트

3.1. 캘린더 (Calendar API)

• 스코프: calendar

• 주요 엔드포인트:

  • GET /v1.0/users/{userId}/calendar/events: 특정 사용자의 일정 목록 조회
  • POST /v1.0/users/{userId}/calendar/events: 새 일정 생성
  • PUT /v1.0/users/{userId}/calendar/events/{eventId}: 기존 일정 수정

• 요청 예시: 새 일정 생성 POST https://www.worksapis.com/v1.0/users/{userId}/calendar/events

  {
    "subject": "Team Meeting",
    "start": {
      "date": "2025-09-18",
      "time": "10:00:00"
    },
    "end": {
      "date": "2025-09-18",
      "time": "11:00:00"
    },
    "attendees": [
      {
        "email": "member1@example.com",
        "isOptional": false
      }
    ]
  }
  

3.2. 주소록 (Contact API)

• 스코프: contact, user
• 주요 엔드포인트:
  • GET /v1.0/contacts: 고객/거래처 연락처 목록 조회
  • POST /v1.0/contacts: 새 연락처 생성
  • GET /v1.0/users/{userId}: 조직 내 사용자 정보 조회

3.3. 메일 (Mail API)

• 스코프: mail
• 주요 엔드포인트:
  • POST /v1.0/users/{userId}/mail: 메일 발송
  • GET /v1.0/users/{userId}/mail/messages/{messageId}: 특정 메일 상세 조회

4. 로빙 연동 아키텍처

4.1. 시크릿 관리 (온프레미스 2서버 환경)

• 원칙: 영구 시크릿(Client Secret, Private Key)은 게이트웨이 서버에만 중앙 집중식으로 보관합니다.
• 구현: 게이트웨이 서버에서 HashiCorp Vault 또는 암호화된 파일 시스템(600 권한)을 사용하여 Client ID/Secret을 관리하고, 컨테이너에는 읽기 전용(:ro)으로 마운트합니다.
• 로빙/스킬 서버: 게이트웨이를 통해 발급된 단기 Access Token만 받아 사용하며, 영구 시크릿을 보관하지 않습니다.

4.2. 인증 흐름 및 토큰 관리

• JWT 키 관리 (JWKS): 게이트웨이는 JWT 서명에 사용하는 공개키 목록을 /.well-known/jwks.json 엔드포인트를 통해 노출하여, 다른 서비스들이 토큰을 안전하게 검증하고 키 교체에 대응할 수 있도록 합니다.
• 토큰 흐름: 로빙/스킬 서버는 외부 API를 직접 호출하는 대신, 게이트웨이에 API 호출을 위임하고 필요한 단기 토큰을 받아 사용합니다.

5. 구현 필요 사항

5.1 파일 생성/수정 목록

생성 필요

• auth-server/app/providers/naverworks.py: OAuth 2.0 인증 플로우 구현
• skill-naverworks/: NAVER WORKS API 전용 스킬 서비스 (포트 8511)

수정 필요

• auth-server/app/main.py: naverworks 라우터 등록 (prefix="/auth/naverworks")
• auth-server/.env: NAVERWORKS_CLIENT_ID, SECRET, REDIRECT_URI 추가
• nginx-deploy: /auth/naverworks, /api/naverworks 라우팅 설정

5.2 구현 플로우 (Slack 패턴 참조)

OAuth 로그인 플로우

# auth-server/app/providers/naverworks.py 구현 필요

@router.get("/login/")
async def naverworks_login():
    # 1. State 생성 → Redis 저장 (TTL 300s)
    # 2. Redirect to https://auth.worksmobile.com/oauth2/v2.0/authorize

@router.get("/callback")
@router.post("/callback")  # form_post 지원
async def naverworks_login_callback():
    # 1. State 검증
    # 2. Code → Token 교환 (POST https://auth.worksmobile.com/oauth2/v2.0/token)
    # 3. Userinfo 조회 (GET https://www.worksapis.com/v1.0/oidc/userinfo)
    # 4. User DB 매핑 (oauth_provider="naverworks")
    # 5. JWT 생성 → Redis temp code → Frontend redirect

Service Account JWT 인증

async def get_service_account_token():
    # 1. Private Key 로드 (파일 시스템)
    # 2. JWT Assertion 생성
    # 3. Token 요청 (grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer)
    # 4. Access Token 캐싱 (Redis TTL 3600s)

5.3 결정/확인 필요 사항

결정사항 (확정)

• Redirect URL 도메인: auth.ro-being.com 사용
• Private Key 저장 경로: auth-server/private_20250917185550.key
• NAVER WORKS 토큰 테이블: naverworks_token (team 스키마 아래, 단수형)

확인필요

• OIDC userinfo 응답 형식: sub, userId 등 정확한 필드명
• Service Account JWT 서명: 알고리즘 (RS256 등)
• Rate Limit: API 호출 제한 및 쿼터
• Private Key 교체 시: 기존 토큰 유효성 유지 여부

6. 참고 자료

• 네이버웍스 개발자 센터 (공식 문서): developers.worksmobile.com
  • 인증 가이드
  • 캘린더 API
  • 주소록 API
  • 메일 API
• 내부 참조 코드:
  • Slack OAuth: auth-server/app/providers/slack.py
  • Gmail OAuth: auth-server/app/providers/gmail_passport.py