[Feat]: Apple 소셜 로그인 API 구현

[juwoojae]

Issue 요약

Apple OAuth 2.0 / OpenID Connect를 연동하여 사용자가 Apple 계정으로 로그인할 수 있도록 구현합니다.

기존 Google / Kakao / Naver OAuth에서 적용한 백엔드 중심 handoff token 방식을 참고하여, Apple 로그인 요청 / callback 수신 / authorization code 검증 / Apple ID Token 검증 / 사용자 정보 조회 및 매핑 / 서비스 토큰 발급 흐름을 구현합니다.

Issue 상세

기존 소셜 로그인 API에서는 Google, Kakao, Naver OAuth 2.0을 연동하여 사용자가 소셜 계정으로 로그인할 수 있도록 구현했습니다.

이번 이슈에서는 Apple 로그인을 추가하여 사용자가 Apple 계정으로도 서비스에 로그인할 수 있도록 확장합니다.

로그인 흐름은 기존 Google OAuth 리팩토링 구조 및 Naver 소셜 로그인 API 구현 방식과 동일하게 백엔드 중심으로 처리합니다.

참고 ISSUE

• [Feat]: 소셜 로그인 API 구현 [Feat]: 소셜 로그인 API 구현 #11
• [Refactor]: OAuth 로그인 구조를 백엔드 중심 handoff token 방식으로 변경 [Refactor]: OAuth 로그인 구조를 백엔드 중심 handoff token 방식으로 변경 #65
• [Feat]: Naver 소셜 로그인 API 구현 [Feat]: Naver 소셜 로그인 API 구현 #92

AS-IS

• Google / Kakao / Naver 소셜 로그인만 지원
• Apple 계정 기반 로그인 미지원
• iOS 환경에서 Apple 로그인 지원 필요
• 소셜 제공자별 로그인 확장 구조 필요

TO-BE

• 앱이 백엔드의 Apple 로그인 시작 endpoint 호출
• 백엔드가 Apple OAuth Authorization URL 생성 및 redirect 수행
• Apple 로그인 완료 후 Apple이 백엔드 callback URL로 redirect
• 백엔드가 authorization code를 수신
• 백엔드가 Apple token endpoint에 code를 전달하여 token 응답 수신
• 백엔드가 Apple ID Token을 검증
• Apple ID Token의 subject 값을 provider id로 사용
• Apple에서 제공하는 email, name 등 사용자 정보를 매핑
• email이 null이거나 비공개 릴레이 이메일일 수 있으므로 방어적 코드 작성
• 조회한 사용자 정보를 기반으로 기존 회원 여부 확인
• 기존 회원은 로그인 처리
• 신규 회원은 회원가입 처리 후 로그인 처리
• 백엔드가 짧은 수명의 1회용 handoff token 생성
• 백엔드가 앱 deep link로 handoff token 전달
• 앱이 handoff token을 백엔드에 전달
• 백엔드가 handoff token 검증 후 서비스 access token / refresh token 발급

이번 구현을 통해 소셜 로그인 제공자를 Apple까지 확장하고, OAuth 핵심 흐름을 백엔드에서 일관되게 관리할 수 있도록 합니다.

또한 앱 딥링크에는 서비스 JWT 또는 Apple access token / id token을 직접 노출하지 않고, 짧은 수명의 handoff token만 전달하여 보안성을 유지합니다.

To do

• Apple Developer 설정 확인
• Apple Services ID / Team ID / Key ID / Private Key 설정 확인
• Apple client id / team id / key id / private key / redirect URI 환경변수 추가
• Apple 로그인 시작 endpoint 설계 및 구현
• Apple OAuth Authorization URL 생성 로직 구현
• Apple OAuth redirect URI를 백엔드 callback URL 기준으로 설정
• Apple callback endpoint 구현
• callback에서 authorization code 수신 로직 구현
• Apple client secret JWT 생성 로직 구현
• Apple token endpoint 연동 및 token 응답 수신 구현
• Apple ID Token 서명 검증 로직 구현
• Apple 공개키 JWKS 조회 및 검증 로직 구현
• Apple ID Token의 issuer / audience / expiration 검증
• Apple subject 값을 provider id로 매핑
• Apple email / name 등 사용자 정보 응답 DTO 작성
• email이 null일 수 있는 케이스 방어적 코드 작성
• Apple 비공개 릴레이 이메일 처리 방식 확인
• 기존 회원 조회 및 신규 회원 가입 처리 로직 연결
• 서비스 가입 가능 조건 검증 로직 반영
• handoff token 생성 로직 연결
• handoff token 저장소 및 TTL 정책 기존 구조 재사용
• callback 성공 시 앱 deep link로 handoff token 전달
• handoff token 교환 후 서비스 access token / refresh token 발급
• 로그인 후 온보딩 필요 여부 반환 스펙 반영
• Apple 로그인 실패 / 취소 / callback 실패 예외 처리
• Swagger 문서 작성
• Apple 소셜 로그인 정상 동작 테스트