設定 OAuth 登入

建立並驗證真實賬戶

身份驗證意味著證明誰在使用該應用程式。啟動 Postgres 並首先使用資料庫指南執行遷移，然後保持 Web 伺服器執行。開啟http://localhost:3000/auth,選擇電子郵件/密碼註冊，輸入您的姓名、電子郵件和密碼，然後提交。保留 EMAIL_PROVIDER=local 進行第一次測試。

當流程請求電子郵件程式碼時，請在另一個瀏覽器選項卡中開啟 http://localhost:3000/mail-preview，找到該地址的最新訊息並將其程式碼複製回登入表單。如果程式碼過期，請請求新的程式碼。這些訊息保留在本地發件箱中；反覆檢查外部收件箱將找不到它們。登出，然後再次登入以確認資料庫支援的帳戶正常工作。

如果註冊報告資料庫連線或缺少表錯誤，請完成資料庫設定而不是啟用社交登入。 Google、GitHub、Apple、X 和 Microsoft 按鈕需要自己的提供商應用程式和回撥設定；僅在其提供程式指南完成後才啟用它。 Better Auth 是出廠預設引擎，不需要付費身份驗證帳戶即可進行本地電子郵件登入。

• 建立賬戶前啟動Postgres
• 電子郵件登入程式碼的使用和故障排除
• 配置Google登入
• 新增 Google 登入
• 新增 GitHub 登入
• 新增 Apple 登入

選擇啟用的登入方式

基礎包含郵箱/密碼、OTP 與可配置的社交認證。Better Auth 負責身份與會話，應用則組合供應商配置與 OTP 的事務性投遞。

只啟用你已配置的社交供應商。供應商客戶端金鑰與認證金鑰留在服務端。

把身份連線到工作區

已認證的 handler 在訪問工作區記錄之前先解析會話狀態。工作區開通必須保持冪等，使重放生命週期鉤子不會建立重複的歸屬記錄。

驗證會話行為

測試登入、無效或過期 OTP、一次性消費、退出與匿名訪問拒絕。記憶體介面卡測試覆蓋 handler 語義；生產資料庫持久化與真實供應商回撥需要單獨驗收。

安裝與配置

1. 將 AUTH_SECRET 設定為至少 32 個隨機字元；可以執行 openssl rand -hex 32 生成。

2. 在各服務商的開發者控制台建立 OAuth 應用，並註冊回撥 URL：預設 AUTH_PROVIDER=better-auth 時為 {APP_URL}/api/auth/callback/<provider>。如果服務商只允許一個回撥地址，請為本地和生產環境分別建立應用；docs/github-auth-setup.md 提供完整的 GitHub 配置流程。

3. 開啟對應服務商開關並設定客戶端 ID 和金鑰：例如 AUTH_GOOGLE_ENABLED、GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET；Apple、GitHub、Microsoft 和 Twitter 使用對應變數。開關開啟但缺少憑據會導致啟動失敗，並指出缺少的變數。

4. Microsoft 的回撥地址會隨認證引擎變化：Better Auth 使用 /api/auth/callback/microsoft，Auth.js 使用 /api/auth/callback/microsoft-entra-id。

AUTH_SECRET=<at-least-32-random-characters>
AUTH_PASSKEY_ENABLED=true
EARLY_ACCESS_INVITE_ONLY=false

AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=…
GITHUB_CLIENT_SECRET=…

# AUTH_APPLE_ENABLED / AUTH_MICROSOFT_ENABLED / AUTH_TWITTER_ENABLED
# follow the same pattern:
# MICROSOFT_CLIENT_ID=…  MICROSOFT_CLIENT_SECRET=…
# TWITTER_CLIENT_ID=…    TWITTER_CLIENT_SECRET=…

# Workspace connected accounts (Settings → Connections):
# CONNECTED_X_CLIENT_ID=          CONNECTED_X_CLIENT_SECRET=
# CONNECTED_GOOGLE_CLIENT_ID=     CONNECTED_GOOGLE_CLIENT_SECRET=
# CONNECTED_MICROSOFT_CLIENT_ID=  CONNECTED_MICROSOFT_CLIENT_SECRET=

# Callbacks to register (Better Auth):
#   {APP_URL}/api/auth/callback/google
#   {APP_URL}/api/auth/callback/apple
#   {APP_URL}/api/auth/callback/github
#   {APP_URL}/api/auth/callback/twitter
#   {APP_URL}/api/auth/callback/microsoft   (Auth.js: microsoft-entra-id)

實現流程

工作區的外部賬戶是另一項功能：CONNECTED_X_*、CONNECTED_GOOGLE_* 和 CONNECTED_MICROSOFT_* 憑據供“設定 → 連線”使用，回撥地址位於 {APP_URL}/api/accounts/{x|google|microsoft}/callback。客戶端 ID 為空時，對應連線流程會關閉；不要複用登入應用的憑據。

客戶端金鑰只保留在伺服器端，和 AUTH_SECRET 一樣；不要放進 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 變數。

登入流程已執行？繼續閱讀《設定 AI》。

驗證與排障

測試首次登入、已有會話、取消授權以及停用服務商的情況。最常見的問題是回撥地址不匹配——註冊地址必須與 APP_URL 和認證引擎的回撥路徑完全一致；修改環境變數後還要重啟應用。