From bb469dad231eace541aeeaf8d4667100a4d29caa Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Thu, 11 Sep 2025 21:36:08 +0900
Subject: [PATCH] =?UTF-8?q?=EB=84=A4=EC=9D=B4=EB=B2=84=20OAuth2=20?=
 =?UTF-8?q?=EC=97=B0=EB=8F=99=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EB=AC=B8?=
 =?UTF-8?q?=EC=84=9C=20=EC=9E=91=EC=84=B1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Authorization Code Grant 흐름 정리
- API 엔드포인트 및 파라미터 명세
- 토큰 갱신/철회 절차
- 구현 체크리스트 및 주의사항
---
 .../naver_oauth2_integration_guide.md         | 133 ++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 300_architecture/integrations/naver_oauth2_integration_guide.md

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