RN 모바일 앱이 provider native SDK로 받은 token을 백엔드가 검증하고 자체 JWT를 발급하는 흐름

모바일 네이티브 로그인 API

RN(React Native) / 하이브리드 모바일 앱이 provider native SDK 로 OAuth 를 직접 수행한 뒤, 받은 idToken / accessToken 을 백엔드가 검증하고 자체 JWT 를 발급하는 흐름.

기존 web OAuth 흐름 (GET /ai/oauth/{provider} 302 redirect 방식) 과 완전 분리되어 있어 web 영향이 없습니다.

흐름 개요

[RN App]
  │  provider native SDK (GoogleSignIn-iOS, Kakao SDK 등) 로 OAuth 직접 수행
  │  Google      → idToken
  │  Kakao/Naver/Facebook → accessToken
  │
  ▼
POST /ai/oauth/native/{provider}
  body: { idToken? | accessToken?, device: "APP" }
  │
  ▼
[Backend]
  │  Google : Google JWKS 로 idToken 서명 + audience + issuer + exp 검증
  │  Kakao  : Kakao API (kapi.kakao.com/v2/user/me) 호출로 user info 추출
  │  Naver  : Naver API (openapi.naver.com/v1/nid/me) 호출 + NaverPay 배송지 호환
  │  Facebook : Graph API debug_token 으로 발급 app_id 일치 확인 + user info 추출
  │  → Member/Influence 회원가입 또는 로그인 처리
  │  → 자체 JWT (access + refresh) 발급
  │
  ▼
TokenDto { memberId, accessToken, refreshToken, isFirstLogin }

엔드포인트

Provider	엔드포인트	입력
Google	`POST /ai/oauth/native/google`	`idToken`
Kakao	`POST /ai/oauth/native/kakao`	`accessToken`
Naver	`POST /ai/oauth/native/naver`	`accessToken`
Facebook	`POST /ai/oauth/native/facebook`	`accessToken`

공통 Request Body

{
  "idToken": "<Google idToken>",
  "accessToken": "<Kakao/Naver/Facebook accessToken>",
  "device": "APP"
}

필드	타입	필수	설명
`idToken`	`string`	Google 만 필수	Google native SDK 가 발급한 ID token (JWT)
`accessToken`	`string`	Kakao/Naver/Facebook 필수	provider native SDK 가 발급한 access token
`device`	`string`	예	항상 `"APP"` 으로 고정. `"WEB"` 입력 시 거부 (native login 은 모바일 앱 전용)

공통 응답

성공 (200 OK)

{
  "memberId": "1234567890",
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
  "isFirstLogin": false
}

공통 에러 코드

HTTP	code	발생 조건
400	`OAUTH_001` MISSING_TOKEN	provider 별 필수 token 누락
400	`OAUTH_002` INVALID_DEVICE	device 값 누락 또는 `WEB` 전달
401	`OAUTH_003` INVALID_ID_TOKEN	idToken 서명/만료/audience 등 JWT 검증 실패 (Google)
401	`OAUTH_007` INVALID_ACCESS_TOKEN	provider API 가 access token 거부 (Kakao/Naver/Facebook)
401	`OAUTH_008` APP_ID_MISMATCH	Facebook debug_token 의 app_id 가 mobile app_id 와 불일치
500	`OAUTH_009` PROVIDER_API_ERROR	provider 서버 응답 파싱 실패 또는 일시 장애

RefreshToken Device 분리

native login 으로 발급된 refresh token 은 Redis 의 {userId}:app 키에 저장됩니다.

이후 토큰 갱신 시 POST /ai/auth/refreshToken/v2 를 호출하여 {userId}:app 키 1종만 조회/갱신하므로, web 세션과 완전히 분리됩니다.

사전 준비 (provider 콘솔)

Google: Google Cloud Console 에서 iOS / Android 별 OAuth Client ID 발급 → 백엔드 sns.google.mobile.{ios|android}.client.id 설정
Kakao: 카카오 디벨로퍼스 → 플랫폼 → iOS Bundle ID / Android 패키지 + 키해시 등록
Naver: 네이버 디벨로퍼스 → API 설정 → iOS URL Scheme + Android 패키지 등록
Facebook: Meta for Developers → 앱 설정 → iOS Bundle ID + Android 키해시 등록 (선택: mobile 전용 app_id 분리)

Apple Sign-In 은 별도 PR 로 추가 예정입니다 (App Store 가이드라인 4.8 대응).

개요

On this page