네이버웍스 API 연동 가이드

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

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

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

1.1. 인증 정보

Client ID: kFJu_ajl6tb8pBiPEEnS
Client Secret: xIz5G0v4wn
- ⚠️ 경고: 이 값은 외부에 노출되어서는 안 되며, Git 등 버전 관리 시스템에 포함하지 마십시오. Vault 또는 암호화된 환경 변수를 통해 안전하게 관리해야 합니다.
Service Account: 86rye.serviceaccount@company-x.partners

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을 발급받아야 합니다. 현재 앱 설정에 따라 아래 두 가지 방식 모두 사용 가능합니다.

구성원 계정으로 인증 (OAuth 2.0 / OIDC): 사용자가 직접 로그인하여 자신의 데이터에 대한 접근을 허용하는 방식입니다. (예: "내 캘린더 일정 조회")
서비스 계정으로 인증 (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. 참고 자료

네이버웍스 개발자 센터 (공식 문서): developers.worksmobile.com
네이버 개발자 포럼: API 관련 실제 질의응답을 참고할 수 있습니다.

4.8 KiB Raw Blame History