> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 新增 Apple 登入

在 Apple Developer 門戶中註冊 App ID、Services ID 和 Sign in with Apple 金鑰，並把客戶端憑據對接到應用。

## 初學者演練

前提條件：Web 應用在本地執行（5 分鐘啟動）、已遷移且能存真實賬戶的資料庫（設定資料庫），以及一個 Apple Developer Program 會員——與移動端賬戶指南註冊的同一個每年 99 美元的賬戶，如果還沒完成，先完成那一步再繼續。下面開發者門戶裡的所有操作都不額外收費。

為什麼重要：每當 iOS 應用提供 Google 或 GitHub 這類第三方社交登入時，App Store 稽核都要求提供 Sign in with Apple；它在 Web 端也是一顆可靠、低摩擦的按鈕——Apple 使用者用裝置上已有的賬戶即可登入。

快速術語：App ID 是應用的註冊識別符號（`com.yourcompany.yourapp`）。Services ID 是 Apple 為 Web 和服務端登入簽發的第二個識別符號——它就是你的客戶端 ID。Return URL 是 Apple 允許把登入使用者送回的精確地址——即套件的 Better Auth 回撥。金鑰是 Apple 只提供一次的 `.p8` 檔案；由你自己把它轉換成客戶端金鑰。

1. 註冊一個帶 Sign in with Apple 能力的 App ID。2. 註冊一個指向它、並持有你的域名和 return URL 的 Services ID。3. 建立 Sign in with Apple 金鑰並下載 `.p8` 檔案。4. 把該金鑰轉換成 client-secret JWT，並設定三個 env 值。

一個實在的限制：Apple 的 return URL 必須是註冊域名上的絕對 `https://` 地址——`localhost` 和裸 `http` 都會被拒絕，所以在裸本地伺服器上無法完整走通按鈕。請在已部署的 URL 上驗證，或把本地伺服器放到 https 隧道（如 `cloudflared tunnel` 或 `ngrok`）後面，並在測試期間註冊隧道域名及其回撥。

[建立 Apple Developer 賬戶](https://supastack.dev/zh-tw/docs/mobile/external-accounts.md)

[設定資料庫](https://supastack.dev/zh-tw/docs/web/setup-database.md)


## 註冊 App ID

1. 開啟 [developer.apple.com/account](https://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 和 return URL

1. 回到 Identifiers，再次點選 +，選擇 Services IDs → Continue。

2. Description：類似 `yourapp web sign-in`。Identifier：再來一個反向域名——慣例是 `com.yourcompany.yourapp.web`——故意與 App ID 不同。這個 Services ID 就是伺服器用於 Web 登入的客戶端 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。

每個 return 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` 是 Services ID（`com.yourcompany.yourapp.web`），不是 App ID。

Apple 不簽發靜態客戶端金鑰，所以 `APPLE_CLIENT_SECRET` 是你用 Team ID、Key ID 和 `.p8` 私鑰自己簽發的 JWT——Better Auth 檔案附帶了生成它的短指令碼。簽發的金鑰最長有效六個月：設個提醒重新生成並更新 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>
```


## 驗證與排錯

在 `/auth` 開啟你的 `APP_URL`——已部署 URL 或 https 隧道——點選 Apple 按鈕，用任意 Apple ID（不必是開發者賬戶）登入，確認回到應用時已登入。

大多數失敗是三種混淆之一：Services ID 與 App ID——客戶端 ID 必須是用於 Web 登入的 Services ID；return URL 不匹配——回撥必須與已註冊的 Return URL 完全相等，包括協議、域名和路徑；或者客戶端金鑰過期/無效——重新生成 JWT，它只是簽發的令牌，不是 `.p8` 內容。

在設定 `AUTH_APPLE_ENABLED=true` 之前，`/auth` 上的 Apple 選項保持停用——檢查 env 名稱並重啟。在沒有 `APPLE_CLIENT_ID` 和 `APPLE_CLIENT_SECRET` 的情況下開啟開關會讓啟動失敗並指出缺失的變數。

iOS 應用訪問的是同一個後端——在其中也釋出 Sign in with Apple，好讓 App Store 稽核接受其他社交按鈕。移動端賬戶指南解釋了稽核的關注點。

[建立移動端賬戶](https://supastack.dev/zh-tw/docs/mobile/external-accounts.md)

[接下來新增 Stripe 支付](https://supastack.dev/zh-tw/docs/web/stripe-payments.md)

[OAuth 提供商概覽](https://supastack.dev/zh-tw/docs/web/setup-oauth.md)


如果你想繼續完成設定，可以閱讀《[新增 Stripe 支付](https://supastack.dev/zh-tw/docs/web/stripe-payments.md)》。


## 下一篇

[新增 Stripe 支付](https://supastack.dev/zh-tw/docs/web/stripe-payments.md)