SidedockSidedock
로그인
Dev Log/[Froppy 개발기 4편] 소셜 로그인 3종 세트 — Google / Kakao / Naver OAuth 연동 실전

[Froppy 개발기 4편] 소셜 로그인 3종 세트 — Google / Kakao / Naver OAuth 연동 실전

#Flutter#NestJS#OAuth#Google#Kakao
froppy
@froppy

12일 전

▣Froppy7개 기록▼ 목록 보기▲ 목록 접기
링크 복사 또는 네이티브 공유

소셜 로그인 3종 세트 — Google / Kakao / Naver OAuth 연동 실전

OAuth 로그인 버튼은 몇 개 안 되지만,
그 뒤에는 제공자 설정, 백엔드 인증, 사용자 매핑, 가입 절차, 앱 복귀 처리가 이어진다.

Froppy에는 Google, Kakao, Naver 로그인을 붙였다.

처음에는 세 제공자의 버튼을 만들고 각각 로그인 API를 연결하면 끝날 줄 알았다. 하지만 실제로는 소셜 제공자마다 프로필 응답 구조와 동의 항목이 달랐고, 신규 사용자와 기존 사용자를 구분하는 가입 흐름도 따로 필요했다.

이번 글에서는 Froppy에서 OAuth 인증이 어떤 흐름으로 동작하도록 구성했는지, 그리고 웹 구현과 모바일 구현 사이에 남은 과제까지 정리해본다.


OAuth 로그인은 어떻게 동작할까

OAuth 로그인을 단순화하면 다음과 같은 흐름이다.

  1. 사용자가 Froppy에서 소셜 로그인 버튼을 누른다.
  2. Flutter 앱이 Froppy 백엔드의 provider 인증 경로로 이동한다.
  3. NestJS Passport가 해당 제공자의 인증 페이지로 리다이렉트한다.
  4. 사용자가 제공자 페이지에서 로그인하고 정보 제공에 동의한다.
  5. 제공자가 백엔드 콜백 주소로 인증 결과를 전달한다.
  6. 백엔드가 프로필을 확인하고 Froppy 사용자 계정과 연결한다.
  7. 기존 회원이면 로그인 결과를, 신규 회원이면 가입 절차를 이어갈 정보를 전달한다.

여기서 중요한 점은 Google, Kakao, Naver가 발급한 토큰과 Froppy 로그인 토큰은 서로 다른 용도라는 것이다.

Froppy는 제공자 인증 이후 자체 사용자 계정을 확인하고, 서비스 API에 사용할 JWT를 별도로 발급한다. Flutter 앱은 이 Froppy JWT를 저장해 이후 API 요청에 사용한다.

sequenceDiagram
    actor User as 사용자
    participant App as Flutter 앱
    participant API as NestJS 백엔드
    participant OAuth as Google / Kakao / Naver
    participant DB as PostgreSQL

    User->>App: 소셜 로그인 선택
    App->>API: GET /auth/{provider}
    API->>OAuth: 인증 페이지로 리다이렉트
    User->>OAuth: 로그인 및 정보 제공 동의
    OAuth->>API: 인증 콜백
    API->>API: Strategy가 프로필 정규화
    API->>DB: 기존 사용자 조회
    alt 기존 사용자
        API->>App: Froppy JWT 전달
    else 신규 사용자
        API->>App: 가입용 임시 토큰 전달
        App->>API: 추가 정보 및 약관 동의 제출
        API->>DB: 사용자 생성
        API->>App: Froppy JWT 전달
    end

NestJS에서 provider별 Strategy 분리하기

Froppy 백엔드는 NestJS Passport를 사용했다.

인증 시작과 콜백은 provider별 경로로 나눴다.

GET /auth/google
GET /auth/google/callback

GET /auth/kakao
GET /auth/kakao/callback

GET /auth/naver
GET /auth/naver/callback

컨트롤러에서는 AuthGuard('google'), AuthGuard('kakao'), AuthGuard('naver')를 사용하고, 각 Guard가 해당 Strategy를 실행한다.

@Get('google')
@UseGuards(AuthGuard('google'))
googleAuth() {
  // Passport가 제공자 인증 페이지로 리다이렉트한다.
}

@Get('google/callback')
@UseGuards(AuthGuard('google'))
googleAuthRedirect(@Request() req, @Res() res) {
  // Strategy가 검증한 결과는 req.user에서 확인한다.
}

각 Strategy가 제공자 프로필을 Froppy가 사용하는 공통 형태로 정리한 다음, AuthService.validateSocialUser()에 넘기는 구조다.

GoogleStrategy ─┐
KakaoStrategy  ─┼─> AuthService.validateSocialUser()
NaverStrategy  ─┘

provider별 차이는 Strategy에서 흡수하고, 계정 조회와 Froppy JWT 발급은 공통 서비스에서 처리하도록 역할을 나눴다.


세 제공자의 프로필은 같지 않았다

OAuth라는 공통 규격을 사용해도 사용자 프로필 응답은 서로 다르다.

Google

Google Strategy에서는 프로필의 ID, 이메일, 이름, 사진을 사용했다.

  • Google 고유 ID를 googleId로 저장
  • 이메일을 Froppy 사용자 검색에 활용
  • 이름은 이름과 성을 조합
  • 프로필 사진 URL을 사용

이메일과 프로필 정보가 제공된다고 가정하기보다, 앱 설정에서 어떤 scope와 동의 항목을 요청하는지 함께 확인해야 했다.

Kakao

Kakao는 이메일이 항상 제공되는 값이 아니었다. 사용자가 이메일 제공에 동의하지 않았거나 해당 정보가 없는 경우를 고려해야 했다.

  • 고유 ID를 kakaoId로 저장
  • 이메일이 없으면 null로 처리
  • 닉네임은 Kakao 계정 프로필에서 우선 확인
  • 닉네임이 없을 때를 위한 대체값 처리

그래서 “모든 소셜 계정에는 이메일이 있다”는 전제로 사용자 식별 로직을 작성하면 문제가 생길 수 있다.

Naver

Naver Strategy는 다른 두 provider와 프로필 응답 구조가 달랐다. 필요한 값이 profile._json 안에 들어 있어 그 구조에 맞춰 추출했다.

  • 고유 ID를 naverId로 저장
  • 이메일, 닉네임, 프로필 이미지 등을 _json에서 확인
  • 실명이나 닉네임이 제공되지 않을 가능성을 고려

세 응답을 한 군데서 억지로 같은 형태라고 가정하기보다는, provider별 Strategy에서 공통 프로필 모델로 바꾸는 편이 이해하기 쉬웠다.


기존 회원과 신규 회원을 나누는 방식

Froppy에서는 OAuth 인증이 성공했다고 즉시 신규 사용자를 DB에 저장하지 않았다.

validateSocialUser()에서 기존 사용자를 찾지 못하면 실제 회원 대신 30분 유효기간의 가입용 임시 토큰(signupToken)을 발급했다. Flutter 앱은 이 토큰을 받아 추가 정보 입력과 약관 동의 화면으로 이동한다.

가입 완료 요청에는 대략 다음 정보가 필요하다.

signupToken
사용자명 등 추가 프로필 정보
필수 약관 동의 내역

백엔드는 가입용 토큰을 검증한 뒤 실제 사용자 계정을 생성하고 Froppy JWT를 발급한다.

이렇게 나누면 소셜 제공자에서 받은 최소 정보만으로 계정을 바로 만드는 대신, Froppy에서 필요한 가입 정보와 동의를 확인한 다음 계정을 만들 수 있다.

계정 연결에서 배운 점

현재 코드는 이메일이 있으면 이메일로 기존 사용자를 먼저 찾고, 찾지 못하면 provider 고유 ID로도 조회한다. 기존 사용자를 찾으면 해당 provider ID가 비어 있을 때 연결한다.

이 방식은 기존 이메일 계정과 소셜 로그인을 이어주는 데 편리하다. 다만 이메일이 같다는 이유만으로 계정을 자동 연결하는 정책은 서비스의 보안 요구와 provider가 보장하는 이메일 검증 수준을 따져 결정해야 한다.

계정 연결을 허용할지, 사용자에게 재인증을 요구할지, 이메일이 없는 계정은 어떻게 처리할지 초기에 정책으로 정해두는 게 좋다.


Flutter에서는 웹과 모바일의 시작 방식이 달랐다

공통 OAuthService에서 provider별 인증 URL을 만들고, 플랫폼 구현체로 실행을 넘겼다.

OAuthService
├── oauth_service_web.dart
└── oauth_service_mobile.dart

조건부 import를 이용해 웹과 모바일에서 같은 서비스 API를 유지하도록 했다.

웹: 현재 브라우저를 백엔드로 이동

웹에서는 window.location.assign()으로 현재 브라우저를 백엔드 OAuth 경로로 이동시킨다.

final url = '$baseUrl/google?action=$action';

if (kIsWeb) {
  OAuthPlatform.openOAuthWindow(url);
}

현재 창을 이용하면 OAuth 제공자 로그인 후 브라우저가 백엔드 콜백을 거쳐 Flutter 웹 앱으로 돌아올 수 있다. Flutter의 콜백 처리 코드는 URL의 결과를 읽고, JWT를 저장한 뒤 사용자 상태를 갱신한다.

신규 회원이라면 가입용 임시 토큰을 받아 추가 가입 화면으로 이동한다.

모바일: 외부 브라우저 실행은 별도의 시작일 뿐

모바일 구현체에서는 url_launcher로 시스템 외부 브라우저를 연다.

await launchUrl(
  uri,
  mode: LaunchMode.externalApplication,
);

하지만 외부 브라우저를 여는 것만으로 OAuth 흐름이 완성되는 것은 아니다. 인증이 끝난 뒤 앱으로 돌아오기 위한 딥링크 설정, 딥링크 수신, 콜백 결과 검증과 토큰 저장이 모두 연결되어야 한다.

현재 코드에는 딥링크 URL을 파싱하는 handleDeepLink()가 있지만, 확인한 앱 코드에서는 이를 실제 앱 링크 수신 이벤트에 연결하는 부분까지 확인되지 않았다. 또한 백엔드 콜백은 프론트엔드 URL로 리다이렉트하는 흐름이다.

따라서 이 구현을 글로 정리할 때는 다음을 구분해야 했다.

  • 외부 브라우저에서 인증을 시작하는 코드가 있다.
  • 모바일 딥링크 결과를 처리하는 함수도 있다.
  • 그러나 이 두 부분이 앱의 실제 딥링크 수신과 백엔드 복귀 경로까지 완성된 상태인지는 별도로 검증해야 한다.

웹에서 잘 동작한다고 모바일에서도 같은 방식으로 동작하는 것은 아니었다. 특히 OAuth 제공자의 redirect URI 등록, Android/iOS 앱 링크 설정, 앱이 종료된 상태에서의 콜백 처리까지 실제 기기에서 확인해야 한다.


OAuth 설정에서 반복해서 확인한 것들

provider 설정은 코드만 맞다고 끝나지 않았다. 각 개발자 콘솔의 설정과 백엔드 설정이 서로 일치해야 했다.

  • Client ID와 Client Secret
  • 제공자별 callback URL
  • 허용된 redirect URI
  • 요청할 scope와 사용자 동의 항목
  • 개발/운영 도메인 구분
  • 웹과 모바일 앱 복귀 주소

특히 callback URL은 provider 콘솔에 등록된 값과 백엔드 callbackURL이 정확히 맞아야 한다. 프로토콜, 도메인, 경로가 조금만 달라도 인증 후 콜백 단계에서 실패할 수 있다.

Client Secret은 Flutter 앱에 넣으면 안 된다. 브라우저와 모바일 앱은 사용자가 값을 확인할 수 있는 클라이언트이므로, 비밀 값은 NestJS 서버의 환경변수나 배포 플랫폼의 Secret 설정에만 둬야 한다.


구현하면서 놓치기 쉬운 보안 포인트

1. URL query string으로 토큰 전달하기

현재 웹 콜백은 프론트엔드 URL의 query parameter를 통해 JWT나 가입용 토큰, 사용자 정보를 전달한다. Flutter는 이를 처리한 뒤 history.replaceState()로 URL을 정리한다.

URL을 빠르게 정리하는 것은 노출 시간을 줄이는 데 도움이 된다. 하지만 query parameter에 토큰을 넣는 것 자체가 안전한 전달 방식이라는 뜻은 아니다. 브라우저 기록, 서버/프록시 로그, 분석 도구, Referer 등에 남을 가능성을 고려해야 한다.

더 안전한 구조로 개선한다면 다음을 검토할 수 있다.

  • 짧은 수명의 일회용 authorization code만 redirect URL로 전달
  • 앱이 백엔드에 code를 보내 JWT를 교환
  • OAuth state 값을 검증해 요청 위조 방지
  • 모바일은 검증된 딥링크/App Link로 앱 복귀
  • 로그에서 인증 코드와 토큰을 마스킹

이 글에 실제 토큰이나 query 값이 포함된 URL을 복사해 넣지 않는 것도 중요하다.

2. Client Secret과 API 키를 문서나 공개 저장소에 올리지 않기

환경변수 파일은 저장소에서 제외하고, 공개 저장소나 블로그에 설정 화면을 캡처할 때도 키가 보이지 않는지 확인해야 한다.

실제 값이 한 번이라도 외부에 노출됐다면 파일에서 지우는 것만으로 끝나지 않는다. 해당 provider 콘솔에서 기존 값을 폐기하고 새 값으로 교체해야 한다.


이번 구현에서 얻은 교훈

소셜 로그인은 버튼 기능이 아니라 사용자 계정 정책이다.
같은 이메일의 계정을 연결할지, 이메일이 없는 사용자를 어떻게 식별할지, 신규 가입을 어디서 완료할지 먼저 정해야 한다.

provider별 프로필 차이는 Strategy 경계에서 정리하는 편이 낫다.
공통 서비스가 Google/Kakao/Naver 응답의 세부 구조까지 알기 시작하면 변경 영향이 커진다.

웹 OAuth와 모바일 OAuth는 별개의 복귀 흐름이다.
외부 브라우저 실행은 모바일 구현의 일부일 뿐이다. 딥링크 수신과 실제 기기 검증까지 이어져야 한다.

인증 결과를 URL에 실어 보내는 방식은 편리하지만 주의가 필요하다.
토큰을 전달한 직후 URL을 지우더라도 이미 URL에 담겼다는 위험은 남는다. 가능하면 일회용 코드 교환 구조를 고려해야 한다.

개발자 콘솔 설정도 코드의 일부처럼 관리해야 한다.
callback URL과 scope가 코드, 환경변수, provider 콘솔에서 어긋나면 원인을 찾기 어렵다. 환경별 체크리스트를 두는 것이 도움이 됐다.


마치며

Google, Kakao, Naver 로그인을 붙이는 과정은 인증 라이브러리를 연결하는 일보다 계정과 가입의 경계를 정하는 일이 더 컸다.

Froppy에서는 Passport Strategy로 provider별 프로필을 정리하고, 공통 서비스에서 기존 회원 조회와 신규 가입용 토큰 발급을 처리했다. 웹은 브라우저 리다이렉트로 연결했지만, 모바일에서는 딥링크와 콜백의 끝까지 검증해야 한다는 과제가 남았다.

세 버튼이 화면에 나란히 놓였다고 해서 인증 흐름도 같은 것은 아니었다. 그 차이를 초기에 설계하고 테스트하는 것이 소셜 로그인 구현의 핵심이었다.


이 시리즈는 총 8편으로 구성됩니다.

  • [1편] 기획 & 아키텍처 — Flutter + NestJS + Cloudflare를 선택한 이유
  • [2편] Flutter로 Web과 Mobile 동시 개발하기
  • [3편] NestJS로 스타트업 백엔드 설계하기
  • [4편] 소셜 로그인 3종 세트 — Google / Kakao / Naver OAuth 연동 실전 ← 현재 글
  • [5편] 결제 시스템 구축 — Toss Payments & PortOne 연동기
  • [6편] Supabase + Cloudflare로 인프라 구성하기
  • [7편] 실시간 채팅 — WebSocket Gateway + Cloudflare R2
  • [8편] 피벗 — Froppy를 접기로 한 결정
이 글이 도움됐다면 좋아요를 눌러주세요

댓글

로그인하면 댓글을 작성할 수 있습니다.