For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/apple-sign-in.md (or send Accept: text/markdown).

Apple 로그인 추가

Apple Developer 포털에서 App ID, Services ID, Sign in with Apple 키를 등록하고 클라이언트 쌍을 앱에 연결합니다.

이 가이드에 대해 질문하기

초보자 연습

전제 조건: 로컬에서 실행 중인 웹 앱(5분 만에 출시), 실제 계정용 마이그레이션된 데이터베이스(데이터베이스 설정), 그리고 Apple Developer Program 멤버십—모바일 계정 가이드가 등록하는 것과 동일한 연간 $99 계정이므로, 아직 완료하지 않았다면 여기를 계속하기 전에 그 단계를 완료하세요. 아래 개발자 포털의 모든 작업은 추가 비용이 없습니다.

중요한 이유: iOS 앱이 Google이나 GitHub 같은 타사 소셜 로그인을 제공할 때마다 App Store 심사는 Sign in with Apple을 요구하며, 웹에서도 마찰이 적은 훌륭한 버튼입니다—Apple 사용자는 기기에 이미 있는 계정으로 로그인합니다.

용어 정리: App ID는 앱의 등록 식별자(com.yourcompany.yourapp)입니다. Services ID는 Apple이 웹 및 서버 로그인을 위해 발급하는 두 번째 식별자로, 이것이 클라이언트 ID가 됩니다. 리턴 URL은 Apple이 로그인한 사용자를 다시 보낼 수 있는 정확한 주소—킷의 Better Auth 콜백입니다. 시크릿 키는 Apple이 한 번만 제공하는 .p8 파일로, 이를 직접 클라이언트 시크릿으로 변환합니다.

1. Sign in with Apple 기능이 있는 App ID를 등록합니다. 2. 그것을 가리키고 도메인과 리턴 URL을 보유하는 Services ID를 등록합니다. 3. Sign in with Apple 키를 만들고 .p8 파일을 다운로드합니다. 4. 키를 클라이언트 시크릿 JWT로 변환하고 세 가지 env 값을 설정합니다.

솔직한 제한: Apple의 리턴 URL은 등록된 도메인의 절대 https:// 주소여야 합니다—localhost와 일반 http는 거부되므로 베어 로컬 서버에서는 버튼을 완전히 시험할 수 없습니다. 배포된 URL에서 확인하거나, https 터널(예: cloudflared tunnel 또는 ngrok)을 통해 로컬 서버를 노출하고 테스트하는 동안 터널 도메인과 그 콜백을 등록하세요.

App ID 등록

1. developer.apple.com/account를 열고 Developer Program 멤버십을 보유한 계정으로 로그인합니다.

2. Certificates, Identifiers & Profiles → Identifiers를 열고 파란색 + 버튼을 클릭합니다.

3. App IDs → Continue를 선택하고 유형은 App 그대로 → Continue.

4. Description: 제품 이름. Bundle ID: Explicit을 선택하고 역도메인 형식 com.yourcompany.yourapp을 입력합니다—iOS 앱을 출시하는 경우 apps/mobile/app.json의 ios.bundleIdentifier와 정확히 일치시켜 두 플랫폼이 하나의 App ID를 공유하도록 합니다.

5. 기능 목록에서 Sign in with Apple을 체크 → Continue → Register.

예상 결과: 식별자가 Identifiers 목록에 Sign in with Apple 기능이 활성화된 상태로 나타납니다. 이 하나의 App ID를 재사용하세요—Services ID와 키 모두 기본 앱으로 여기에 연결됩니다.

Services ID 및 리턴 URL 등록

1. Identifiers로 돌아가 다시 +를 클릭하고 Services IDs → Continue를 선택합니다.

2. Description: yourapp web sign-in 같은 것. Identifier: 또 다른 역도메인 이름—com.yourcompany.yourapp.web이 관례입니다—App ID와 의도적으로 다르게 합니다. 이 Services ID가 서버가 웹 로그인에 사용하는 클라이언트 ID입니다. 정확히 복사한 후 Continue → Register.

3. 목록에서 새 Services ID를 선택하고 Sign in with Apple을 체크한 뒤 Configure를 클릭합니다.

4. 대화 상자에서 Primary App ID를 이전 섹션의 App ID로 설정합니다. Website URLs에 도메인(예: yourdomain.com)을 추가하고 Return URLs에 https://yourdomain.com/api/auth/callback/apple을 추가합니다—해당 경로는 킷의 Better Auth 콜백 {APP_URL}/api/auth/callback/apple입니다. Save → Continue → Save.

각 리턴 URL은 등록된 도메인의 절대 https:// 주소여야 합니다: localhost, 베어 IP 주소, http는 거부됩니다. 로컬 개발에서는 앱을 https 터널 뒤에서 실행하고, 터널 도메인을 Services ID에 추가하고, https://<tunnel-domain>/api/auth/callback/apple을 등록하고, 테스트하는 동안 APP_URL을 터널 URL로 설정합니다.

예상 결과: Services ID가 Sign in with Apple → Enabled로 표시됩니다. 포털이 도메인을 거부하면 먼저 계정 페이지에서 도메인 소유권 확인을 완료하세요.

Sign in with Apple 키 만들기

1. 왼쪽 사이드바에서 Keys → +를 엽니다. 키 이름을 지정하고(예: yourapp sign-in key) Sign in with Apple을 체크하고 Configure를 클릭하고 App ID를 Primary App ID로 선택 → Save → Continue → Register.

2. 확인 화면에서 Key ID를 기록한 다음 Download를 클릭합니다—.p8 파일은 정확히 한 번만 제공됩니다. 잃어버리면 키를 취소하고 다른 키를 만드세요. Apple은 사본을 보관하지 않습니다.

3. Team ID도 기록하세요—개발자 계정 페이지 오른쪽 상단, 계정 이름 옆에 인쇄되어 있습니다.

예상 결과: 이제 .p8 파일, Key ID, Team ID 세 가지 값을 보유했습니다. .p8 파일을 Git에 넣지 마세요. 이 파일은 개발자 계정으로 서명합니다.

앱에 값 추가

킷은 아래 세 줄만 기대합니다—모든 소셜 공급자가 사용하는 것과 동일한 clientId/clientSecret 쌍입니다. APPLE_CLIENT_ID는 App ID가 아니라 Services ID(com.yourcompany.yourapp.web)입니다.

Apple은 정적 클라이언트 시크릿을 발급하지 않으므로 APPLE_CLIENT_SECRET은 Team ID, Key ID, .p8 개인 키로 직접 서명하는 JWT입니다—Better Auth 문서에 그 짧은 생성 스크립트가 포함되어 있습니다. 서명된 시크릿은 최대 6개월 동안만 유효합니다. 다시 생성하여 env 값을 업데이트하도록 미리 알림을 설정하세요. 만료되는 순간 로그인이 실패합니다. .p8 파일의 내용이나 원시 Key ID를 env에 붙여넣지 마세요—거기에는 생성된 JWT만 들어갑니다.

클라이언트 시크릿과 .p8 파일은 서버 전용입니다: NEXT_PUBLIC_/EXPO_PUBLIC_ 변수에 절대 넣지 말고 커밋도 하지 마세요—프로덕션에서는 호스트의 시크릿 저장소를 통해 설정합니다. 편집 후 개발 서버를 재시작하세요. env 변경은 시작 시 읽힙니다.

# apps/web/.env.local
AUTH_APPLE_ENABLED=true
APPLE_CLIENT_ID=com.yourcompany.yourapp.web   # the Services ID, not the App ID
APPLE_CLIENT_SECRET=<JWT signed with Team ID + Key ID + .p8>

확인 및 문제 해결

APP_URL—배포된 URL 또는 https 터널—의 /auth를 열고 Apple 버튼을 클릭하고 임의의 Apple ID(개발자 계정일 필요는 없습니다)로 로그인한 후 로그인된 상태로 돌아오는지 확인합니다.

대부분의 실패는 세 가지 혼동 중 하나입니다: Services ID 대 App ID—클라이언트 ID는 웹 로그인용 Services ID여야 합니다. 리턴 URL 불일치—콜백은 프로토콜, 도메인, 경로를 포함하여 등록된 Return URL과 정확히 일치해야 합니다. 또는 만료/유효하지 않은 클라이언트 시크릿—JWT를 다시 생성하세요. 이것은 .p8 내용이 아니라 서명된 토큰일 뿐입니다.

AUTH_APPLE_ENABLED=true를 설정할 때까지 /auth의 Apple 옵션은 비활성화된 상태입니다—env 이름을 확인하고 재시작하세요. APPLE_CLIENT_ID와 APPLE_CLIENT_SECRET 없이 플래그를 활성화하면 시작이 실패하고 누락된 변수를 지목합니다.

iOS 앱도 같은 이 백엔드에 도달합니다—App Store 심사가 다른 소셜 버튼을 받아들이도록 그 안에도 Sign in with Apple을 포함하세요. 심사가 무엇을 찾는지는 모바일 계정 가이드가 설명합니다.

설정을 계속하려면 Stripe 결제 추가 가이드를 읽어보세요.