113 lines
4.8 KiB
Markdown
113 lines
4.8 KiB
Markdown
# 네이버웍스 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**을 발급받아야 합니다. 현재 앱 설정에 따라 아래 두 가지 방식 모두 사용 가능합니다.
|
|
|
|
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`
|
|
```json
|
|
{
|
|
"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](https://developers.worksmobile.com)
|
|
- [인증 가이드](https://developers.worksmobile.com/kr/docs/auth)
|
|
- [캘린더 API](https://developers.worksmobile.com/kr/document/10070?lang=ko)
|
|
- [주소록 API](https://developers.worksmobile.com/kr/docs/contact)
|
|
- [메일 API](https://developers.worksmobile.com/kr/docs/mail)
|
|
- **네이버 개발자 포럼:** API 관련 실제 질의응답을 참고할 수 있습니다.
|