AI Skills
oauth

oauth

熱門

設定 OAuth 提供者（Google、Apple、Microsoft、Facebook、GitHub 等）以搭配 portless 本機開發網址使用。當設定 OAuth 重新導向 URI、修正「redirect_uri_mismatch」或「invalid redirect」錯誤、設定本機開發的登入提供者，或提供者拒絕 .localhost 子網域時使用。觸發情境包括「OAuth 無法搭配 portless 運作」、「重新導向 URI 不符」、「Google/Apple/Microsoft 登入在本機失敗」、「設定本機開發的 OAuth」，或任何涉及使用 portless 網域的 OAuth 回呼網址的任務。

1萬星標
334分支
更新於 2026/7/30
獲取技能源代碼

相關技能

network-config-validation24萬issue-triage8.1萬agent-security-manager7.2萬
SKILL.md
唯讀
名稱
oauth
描述

設定 OAuth 提供者（Google、Apple、Microsoft、Facebook、GitHub 等）以搭配 portless 本機開發網址使用。當設定 OAuth 重新導向 URI、修正「redirect_uri_mismatch」或「invalid redirect」錯誤、設定本機開發的登入提供者，或提供者拒絕 .localhost 子網域時使用。觸發情境包括「OAuth 無法搭配 portless 運作」、「重新導向 URI 不符」、「Google/Apple/Microsoft 登入在本機失敗」、「設定本機開發的 OAuth」，或任何涉及使用 portless 網域的 OAuth 回呼網址的任務。

搭配 Portless 的 OAuth

OAuth 提供者會根據網域規則驗證重新導向 URI。.localhost 子網域在大多數提供者上會失敗，因為它們不在公用尾碼清單中，或遭到明確封鎖。Portless 透過 --tld 解決此問題，讓應用程式在真實且有效的網域上提供服務。

問題

當 portless 使用預設的 .localhost TLD 時，OAuth 提供者會拒絕類似 http://myapp.localhost:1355/callback 的重新導向 URI：

提供者 localhost .localhost 子網域 原因
Google 允許 拒絕 不在其內建的 PSL 中
Apple 拒絕 拒絕 完全不允許 localhost
Microsoft 允許 允許 對 localhost 的處理較寬鬆
Facebook 允許 不一定 必須精確註冊每個 URI
GitHub 允許 允許 較寬鬆

Google 和 Apple 最嚴格。Microsoft 和 GitHub 對 localhost 較寬鬆。

解決方法

使用有效的 TLD，讓重新導向 URI 通過提供者驗證：

portless proxy start --tld dev
portless myapp next dev
# -> https://myapp.dev

公用尾碼清單中的任何 TLD 都適用：.dev、.app、.com、.io 等。

使用您擁有的網域

像 .dev 這樣的裸 TLD 表示 myapp.dev 可能與真實網域衝突。請在您控制的網域下使用多段式 TLD，這樣應用程式名稱保持簡潔，而網域結構位於 TLD 中：

portless proxy start --tld local.yourcompany.dev
portless myapp next dev
# -> https://myapp.local.yourcompany.dev

這可確保不會有對外流量到達您未擁有的資源。對於團隊，請設定萬用字元 DNS 記錄（*.local.yourcompany.dev -> 127.0.0.1），這樣每位開發者都能獲得解析，而無需修改 /etc/hosts，且所有開發者在提供者主控台中共享相同的重新導向 URI。

提供者設定

Google

  1. 前往 Google Cloud Console > 憑證
  2. 建立或編輯 OAuth 2.0 用戶端 ID（Web 應用程式）
  3. 將 portless 網域新增至 已授權的 JavaScript 來源：https://myapp.dev
  4. 將回呼新增至 已授權的重新導向 URI：https://myapp.dev/api/auth/callback/google

Google 會根據公用尾碼清單驗證網域。網域必須以公認的 TLD 結尾。.localhost 子網域無法通過此檢查；.dev、.app、.com 等都可以通過。

.dev 和 .app 需要 HTTPS（已預先載入 HSTS）。Portless 會透過 --https 自動處理。

Apple

Apple 登入完全不允許 localhost 或 IP 位址。

  1. 前往 Apple Developer > Certificates, Identifiers & Profiles
  2. 註冊 Services ID
  3. 設定「使用 Apple 登入」，將 portless 網域新增為 Return URL：https://myapp.dev/api/auth/callback/apple

網域必須是真實、可公開解析的網域名稱。由於 portless 會在本機將網域對應到 127.0.0.1，瀏覽器可以解析，但 Apple 的伺服器端驗證可能要求網域也能公開解析。如果 Apple 拒絕該網域，請為您的開發子網域新增指向 127.0.0.1 的公開 DNS A 記錄。

Microsoft（Entra / Azure AD）

  1. 前往 Azure 入口網站 > 應用程式註冊
  2. 建立或編輯應用程式註冊
  3. 在 驗證 下，新增 Web 重新導向 URI：https://myapp.dev/api/auth/callback/azure-ad

Microsoft 允許 http://localhost 搭配任何連接埠用於開發。在大多數情況下，它也接受 .localhost 子網域。為了跨提供者的一致性，仍建議使用 portless 搭配自訂 TLD。

Facebook（Meta）

  1. 前往 Meta for Developers > 應用程式儀表板
  2. 在 Facebook 登入 > 設定 下，將 portless URL 新增至 有效的 OAuth 重新導向 URI：https://myapp.dev/api/auth/callback/facebook

Facebook 要求每個重新導向 URI 都必須精確註冊（不支援萬用字元）。嚴格模式（預設啟用）會強制精確比對。

GitHub

  1. 前往 GitHub Developer Settings > OAuth Apps
  2. 設定 Authorization callback URL：https://myapp.dev/api/auth/callback/github

GitHub 對 localhost 和子網域較寬鬆。自訂 TLD 並非嚴格必要，但可保持設定一致。

驗證程式庫設定

NextAuth / Auth.js

將 NEXTAUTH_URL 設定為符合 portless 網域：

NEXTAUTH_URL=https://myapp.dev

NextAuth 使用此變數來建構回呼 URL。若未設定，回呼可能使用 localhost 而導致不符。

Passport.js

在每個策略中將 callbackURL 設定為使用 portless 網域：

new GoogleStrategy({
  clientID: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  callbackURL: process.env.BASE_URL + "/auth/google/callback",
});

在您的環境中設定 BASE_URL=https://myapp.dev。

通用 / 手動

讀取 portless 注入到子處理程序中的 PORTLESS_URL 環境變數：

const baseUrl = process.env.PORTLESS_URL || "http://localhost:3000";
const callbackUrl = `${baseUrl}/auth/callback`;

疑難排解

「redirect_uri_mismatch」或「invalid redirect URI」

OAuth 流程中傳送的重新導向 URI 與提供者註冊的不符。請檢查：

  1. 提供者註冊的重新導向 URI 與 portless 網域完全相符（協定、主機、路徑）
  2. NEXTAUTH_URL 或同等變數已設定為 portless URL（而非 localhost）
  3. Proxy 正在以正確的 TLD 執行（使用 portless list 驗證）

提供者要求 HTTPS

.dev 和 .app TLD 已預先載入 HSTS，因此瀏覽器會強制使用 HTTPS。啟動 proxy：

portless proxy start --tld dev

Portless 預設在連接埠 443 上使用 HTTPS（會自動以 sudo 提升權限）。執行 portless trust 將本機 CA 新增至系統信任儲存區，以消除瀏覽器警告。

Apple 拒絕該網域

Apple 可能要求網域可公開解析。為您的開發子網域新增指向 127.0.0.1 的 DNS A 記錄：

myapp.local.yourcompany.dev  A  127.0.0.1

或使用萬用字元：*.local.yourcompany.dev A 127.0.0.1。

登入後回呼前往錯誤的 URL

驗證程式庫正在從 localhost 而非 portless 網域建構回呼 URL。請設定適當的環境變數：

  • NextAuth：NEXTAUTH_URL=https://myapp.dev
  • Auth.js v5：AUTH_URL=https://myapp.dev
  • 手動：PORTLESS_URL 會自動注入；請將其用作基礎 URL

範例

請參閱 examples/google-oauth 取得使用 --tld dev 搭配 Next.js + NextAuth + Google OAuth 的完整可運作範例。