diff --git a/300_architecture/integrations/naver_oauth2_integration_guide.md b/300_architecture/integrations/naver_oauth2_integration_guide.md new file mode 100644 index 0000000..5b41647 --- /dev/null +++ b/300_architecture/integrations/naver_oauth2_integration_guide.md @@ -0,0 +1,133 @@ +# 네이버 OAuth2 연동 구현 가이드 + +## 작성일: 2025-09-11 +## 목적: 네이버 로그인 API 연동 절차 정리 + +--- + +## 1. 사전 준비 + +### 애플리케이션 등록 +- 네이버 개발자 센터에서 앱 등록 +- Client ID, Client Secret 발급 +- 콜백 URL 정확히 등록 (URL 인코딩 필수) +- API 권한 관리에서 필요 항목 활성화 (미설정 시 403 오류) + +--- + +## 2. OAuth2 흐름 + +### Step 1: 사용자 인증 (Authorization Code) +``` +GET https://nid.naver.com/oauth2.0/authorize +?response_type=code +&client_id={CLIENT_ID} +&redirect_uri={URL_ENCODED_CALLBACK} +&state={RANDOM_STATE} +``` + +**주요 파라미터:** +- `response_type`: 항상 "code" +- `state`: CSRF 방어용 난수 (세션 저장 후 검증 필수) +- `redirect_uri`: 등록된 콜백과 정확히 일치 + +### Step 2: 토큰 교환 +``` +GET/POST https://nid.naver.com/oauth2.0/token +?grant_type=authorization_code +&client_id={CLIENT_ID} +&client_secret={CLIENT_SECRET} +&code={AUTHORIZATION_CODE} +&state={STATE} +``` + +**응답 데이터:** +```json +{ + "access_token": "AAAAOLtM...", + "refresh_token": "c8ceMEJi...", + "token_type": "bearer", + "expires_in": 3600 +} +``` + +### Step 3: 사용자 프로필 조회 +``` +GET https://openapi.naver.com/v1/nid/me +Headers: Authorization: Bearer {ACCESS_TOKEN} +``` + +**응답 구조:** +```json +{ + "resultcode": "00", + "message": "success", + "response": { + "id": "32742776", // 앱별 고유 식별자 + "email": "user@naver.com", + "name": "홍길동", + "nickname": "닉네임" + } +} +``` + +--- + +## 3. 토큰 관리 + +### 토큰 갱신 +``` +GET https://nid.naver.com/oauth2.0/token +?grant_type=refresh_token +&client_id={CLIENT_ID} +&client_secret={CLIENT_SECRET} +&refresh_token={REFRESH_TOKEN} +``` + +### 연동 해제 +``` +GET https://nid.naver.com/oauth2.0/token +?grant_type=delete +&client_id={CLIENT_ID} +&client_secret={CLIENT_SECRET} +&access_token={ACCESS_TOKEN} +&service_provider=NAVER +``` + +--- + +## 4. 구현 체크리스트 + +- [ ] 네이버 개발자 센터 앱 등록 +- [ ] Client ID/Secret 환경변수 설정 +- [ ] 콜백 URL 등록 및 인코딩 처리 +- [ ] State 파라미터 생성/검증 로직 +- [ ] Authorization 엔드포인트 리다이렉트 +- [ ] 콜백 처리 및 code 교환 +- [ ] Access Token으로 프로필 조회 +- [ ] Refresh Token 갱신 로직 +- [ ] 연동 해제 기능 + +--- + +## 5. 주의사항 + +1. **state 필수**: CSRF 공격 방어, 세션 저장 후 검증 +2. **redirect_uri**: URL 인코딩 필수, 등록값과 정확히 일치 +3. **권한 설정**: 개발자 센터에서 API 권한 미리 활성화 +4. **토큰 타입**: Bearer 토큰 형식 준수 +5. **에러 처리**: error, error_description 파라미터 확인 + +--- + +## 6. 에러 코드 + +| 코드 | 설명 | 해결방법 | +|-----|------|---------| +| 403 | 권한 없음 | API 권한 관리에서 활성화 | +| 401 | 인증 실패 | 토큰 만료 확인, 갱신 필요 | +| 024 | 잘못된 인증 | state 불일치, CSRF 체크 | + +--- + +**참고**: 네이버는 외부 로그아웃 API 미제공, scope 파라미터 불필요 (동의 화면에서 처리) \ No newline at end of file