소셜 로그인 개발 명세 (FRD)¶

요지¶

OAuth2.0 소셜 가입·로그인(카카오·네이버·구글)을 어떻게 구현하는지 정리한다. 분기의 주체는 백엔드다 — Provider 인증을 마치고 돌아오면, 그 이메일이 이미 있는지·소셜 연동이 돼 있는지를 보고 즉시 로그인/연동/신규 가입으로 갈래를 나눈다. 여기에 Age Gate, 이메일 충돌, Provider가 빠뜨린 정보 보강까지 서버에서 처리한다. OAuth 자격증명 값은 인프라 설정(infra)에만 둔다.

상위 PRD (링크 · 변경 시 알림)¶

기획은 prd(바뀌면 이 문서도 갱신), 회원 도메인은 member, 이메일 가입과 겹치는 부분은 회원가입 개발 명세 (FRD)를 본다.

기술 접근 · 아키텍처¶

백엔드 분기 플로우¶

소셜 로그인 클릭 → Provider 인증·리다이렉션 → 백엔드:
  1. 미지원 플랫폼 → 400번대 에러
  2. 이메일 존재 여부 확인
     ├ 이메일 有 + 연동 完 → 토큰 반환(즉시 로그인)
     ├ 이메일 有 + 연동 無 → 토큰 반환 + 소셜 연동(Link)
     └ 이메일 無(신규) → 임시 토큰 발급 + 소셜 연동 + 추가정보 입력 페이지로

필수 정보 입력 필터: BE 매 요청 시 프로필 완성 여부 체크 → 미완성 예외 → FE는 필수 정보 입력 창으로 이동.
신규 회원: 소셜 기반 기본정보만 저장 후 회원가입(추가 정보) 페이지로. 만료 짧은 임시 액세스 토큰으로 진행.

정책·예외¶

연령(4.1): Provider birthyear/birthday/age_range 기준. U14 → 즉시 가입 불가. Unknown → A14+와 동일 처리(가입 허용).
이메일 중복(4.2): 신규 가입 중단 → 계정 연동 확인 화면. 기존 계정 비밀번호 인증 성공 시 Provider 정보 Link → 즉시 로그인. 실패 시 "비밀번호가 일치하지 않습니다" 재시도.
이메일/생년 미제공(4.5): 이메일은 Unique Key — 미제공 시 프로필 확인 단계에서 필수 입력(중복 시 4.2 적용). 생년 미제공 → Unknown(가입 허용), 생년월일 선택 입력 유도 가능.
인증 실패/취소(4.4): 진입 화면 복귀 + 오류 안내·재시도.

API · 데이터 모델¶

OAuth 흐름의 핵심은 Provider가 인증을 마치고 우리 서버로 돌아오는 콜백 한 곳이다. 여기서 모든 분기가 결정된다.

동작	엔드포인트	비고
소셜 콜백	`GET /api/auth/{provider}/callback?state={inviteToken}`	provider 인증 결과 처리, `state`에 초대 토큰 있을 시 수락 API redirect

데이터 쪽으로는 회원(Member)에 Provider 연동 정보(Provider명·ID)를 붙이고, 이메일을 회원 식별 Unique Key로 쓴다. OAuth 자격증명은 인프라 설정(infra)에만 둔다.

프런트 화면(6.1~6.6)과 문구는 design에 정리돼 있다.

의존성 · 영향 범위¶

회원 도메인(member, Provider 연동·이메일 Unique Key)과 이메일 가입의 추가정보·약관(회원가입 개발 명세 (FRD)), OAuth 자격증명(infra)에 기댄다.

학생 초대와도 맞물린다. 초대 링크로 들어온 사람이 소셜로 가입할 때, 초대 토큰을 OAuth state에 실어 보냈다가 콜백에서 복원해 수락 API로 이어 준다. 자세한 토큰 유지 방식은 학생 초대 개발 명세 (FRD)에 있다.

테스트 계획¶

공통 케이스·E2E 전략은 qa-playbook을 따른다. 이 기능에서 꼭 볼 것은 Provider별 가입·로그인, 이메일 중복 시 연동(비밀번호 인증 성공/실패), Age Gate(U14 차단·Unknown 진행), 이메일·생년 미제공 시 프로필 보강, 콜백 실패·취소 복귀, 그리고 초대 토큰이 state로 유지되는지다.

작업 분해 (이슈 링크)¶

진행·완료 상태는 status와 GitHub 이슈에서 확인한다. 관련 이슈: Jira BTS-244.