DOCS/journey/ideas/250911_naver_oauth2_integration_guide.md

네이버 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}

응답 데이터:

{
  "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}

응답 구조:

{
  "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 파라미터 불필요 (동의 화면에서 처리)