Kakao OAuth 연동 가이드 (모바일)

SleepZ 모바일 앱이 Kakao OAuth 로그인을 처리할 때의 기본 흐름과 웹 프런트엔드(apps/dha-sleep-web)와의 차이점을 정리했습니다. 모바일 팀은 아래 내용을 기반으로 API 계약을 검토하고, 필요 시 백엔드와 추가 범위를 조율하세요.

1. 모바일 기본 흐름

인가 URL 요청
- 백엔드 GET /auth/oauth/kakao를 호출해 authorizationUrl과 state를 수신합니다.
- 모바일 SDK(WebView 또는 Custom Tab)를 사용해 authorizationUrl로 리다이렉트합니다.
Kakao 콜백 수신
- Kakao 개발자 콘솔에 등록된 redirectUri(예: sleepz://auth/kakao)로 돌아옵니다.
- 앱은 리다이렉트 URI에서 code, state(및 오류 파라미터)를 파싱합니다.
토큰 교환
- 앱이 직접 백엔드 표준 콜백(GET /auth/oauth/kakao/callback) 또는 향후 제공될 전용 모바일 API에 code, state, redirectUri를 전달해 액세스/리프레시 토큰을 응답으로 받습니다.
- 응답 토큰은 모바일 보안 스토리지(Keychain, Keystore 등)에 저장합니다.
세션 유지
- 이후 API 요청은 Bearer 토큰 헤더 방식으로 처리하며, 쿠키 기반 세션을 사용하지 않습니다.

웹 프런트는 Next.js App Router에서 HttpOnly 쿠키를 내려 주기 위해 POST /auth/oauth/kakao/exchange(프런트 전용) 엔드포인트를 사용합니다. 이 엔드포인트는 다음과 같은 이유로 모바일에서 그대로 활용하기 어렵습니다.

쿠키 기반 세션 관리: 웹은 SameSite/Lax 설정의 쿠키가 필요하지만, 모바일 앱은 HttpOnly 쿠키를 다루기 어렵고 저장 위치도 통일되어 있지 않습니다.
리다이렉트 컨텍스트: 웹 브라우저는 동일한 도메인으로 돌아오지만, 모바일은 앱 스킴으로 돌아와서 별도의 네이티브 처리가 필요합니다.
보안/스토리지 정책: 모바일은 OS 제공 보안 스토리지에 토큰을 저장하는 것이 표준이며, 쿠키에 의존하지 않습니다.

따라서 모바일에서는 웹 전용 POST /auth/oauth/kakao/exchange 대신 표준 콜백(GET /auth/oauth/kakao/callback) 응답을 재사용하거나, 모바일 용으로 협의된 별도 엔드포인트를 통해 토큰을 발급받아야 합니다.

모바일 전용 토큰 교환 API가 필요한 경우, apps/dha-sleep-api에 /auth/oauth/kakao/mobile-exchange(가칭) 같은 엔드포인트 추가를 제안하고, 응답 포맷을 Bearer 토큰 중심으로 정의합니다.
TimeMachine 시계 의존 여부와 토큰 만료 시각 처리 방식을 명확히 문서화합니다.
앱이 백그라운드에서 토큰을 갱신하는 시나리오(Refresh Token 로테이션)를 추가로 설계해야 합니다.
Kakao SDK 업데이트에 따른 redirectUri 허용 정책 변화를 주기적으로 검토합니다.