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