From eaddb852be06657332f7d2ff210a85dbcb6cb1c9 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Fri, 27 Feb 2026 14:10:55 +0900 Subject: [PATCH] docs: record naverworks unauthorized_client refresh incident and recovery --- ...esh_unauthorized_client_reauth_recovery.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 journey/troubleshooting/260227_naverworks_refresh_unauthorized_client_reauth_recovery.md diff --git a/journey/troubleshooting/260227_naverworks_refresh_unauthorized_client_reauth_recovery.md b/journey/troubleshooting/260227_naverworks_refresh_unauthorized_client_reauth_recovery.md new file mode 100644 index 0000000..27f4cd3 --- /dev/null +++ b/journey/troubleshooting/260227_naverworks_refresh_unauthorized_client_reauth_recovery.md @@ -0,0 +1,70 @@ +# NAVER WORKS Refresh `unauthorized_client` 장애 및 재인증 복구 기록 + +**작성일**: 2026-02-27 +**작성자**: Codex +**상태**: 완료 (재인증으로 복구 확인) + +## 문제 요약 + +- `auth-server`의 `POST /auth/naverworks/passport/refresh`가 2026-02-27부터 반복 실패 +- 에러 본문: `{"error":"unauthorized_client"...}` +- 증상 구간 동안 NAVER WORKS 토큰 갱신 성공 로그/DB 갱신이 중단됨 + +## 확인된 사실 (로그/DB 기준) + +1. **시각 전환점 (KST 기준)** +- `2026-02-26 09:00`: refresh `200 OK` +- `2026-02-27 09:00`부터: 동일 user_id 요청이 즉시 `500` + `unauthorized_client` + +2. **오류 원문** +- `{"error_description":"Failed to refresh token with request.","error":"unauthorized_client","error_uri":"See document on https://developers.worksmobile.com/docs/auth-oauth"}` + +3. **DB 상태** +- 장애 중 `naverworks_token.updated_at`가 `2026-02-26 09:00:00+09`에서 멈춤 +- 즉, 갱신 성공 이벤트가 없어 새 토큰 저장 자체가 발생하지 않음 + +4. **클라이언트 값 일치 확인** +- DB `oauth_config.client_id/client_secret`와 Console 표시값 일치 확인 +- 단순 오타/환경변수 불일치 가능성은 낮음 + +## 원인 해석 + +- RFC 6749 Section 5.2 정의상 `unauthorized_client`는 "해당 클라이언트가 해당 grant type 사용 권한이 없음"을 의미 +- 이번 패턴은 로컬 저장 로직 결함보다, NAVER WORKS 측에서 해당 클라이언트/권한부여 상태를 거부한 상태와 일치 + +## 실제 복구 절차 + +1. 사용자 재인증 URL 호출 +- `GET /auth/naverworks/passport/install?user_id={uuid}&return_url=...` + +2. 사용자 브라우저에서 NAVER WORKS 로그인/동의 완료 + +3. 즉시 refresh 재테스트 +- `POST /auth/naverworks/passport/refresh?user_id={uuid}` + +## 복구 검증 결과 + +- 재인증 직후 refresh 응답: `200 OK` +- 응답 본문: `{"success":true,...,"has_refresh_token":true}` +- DB `updated_at`: `2026-02-27 14:08:32+09`로 갱신 확인 +- 결론: 재인증으로 토큰/권한부여 상태 정상화 + +## 왜 재인증이 효과적이었는가 + +- 기존 refresh 체인이 NAVER WORKS 측에서 거부되고 있었고, +- 재인증으로 새 authorization code/토큰 체인을 다시 발급받으면서 권한부여 상태가 회복됨 + +## 재발 시 즉시 체크리스트 + +1. `auth-server` 로그에서 `2/26 성공 -> 2/27 실패` 형태 전환점 확인 +2. `naverworks_token.updated_at` 정지 여부 확인 +3. Console의 `client_id/client_secret`와 DB `oauth_config` 일치 확인 +4. 사용자 재인증 수행 후 refresh `200` 여부 확인 +5. 재인증 후에도 실패 시 Console 감사로그(변경 이력) 및 NAVER WORKS 지원 문의 + +## 관련 근거 + +- RFC 6749 §5.2: `unauthorized_client` 정의 +- NAVER WORKS OAuth 문서: token refresh 파라미터/흐름 +- 서버 실측 로그: `auth-server` timestamps +- DB 실측: `main_db.naverworks_token.updated_at`