OAuth 2.1 導入指南

本指南說明如何安全地授權連結的應用程式平台存取您的服務。如要整合連結的應用程式 MCP，強烈建議使用業界標準的委派授權機制 OAuth 2.1，並搭配程式碼交換證明金鑰 (PKCE)，確保使用者資料享有最高安全性，並提升「代理」流程的可靠性。連結應用程式平台支援授權碼授權類型，並提供 Proof Key for Code Exchange (PKCE) 參數。

所有 OAuth 2.1 都必須使用 PKCE，OAuth 2.0 則可選擇是否使用。

如要啟用自動探索功能並簡化新手上路流程，授權伺服器必須支援授權伺服器中繼資料擴充功能，也稱為 OAuth 探索。

提示：為避免使用者體驗不佳，以及需要重新連結已連結帳戶，最重要的一點是使用永久連結管理更新權杖生命週期。

Gemini MCP 如何擷取設定 JSON

Gemini MCP 控制台會嘗試從下列網址擷取設定 JSON，順序如本節所示。

注意：Gemini MCP 控制台會使用第一個傳回回應的網址，包括錯誤。請確認偏好的端點可連線，並傳回 HTTP 200。

如果授權伺服器網址位於網域的頂層 (例如 https://auth.example.com)，Gemini 會將標準「已知」目錄附加至網域，並依下列順序尋找伺服器：

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

如果授權伺服器網址位於網域的特定子目錄或路徑 (例如 https://auth.example.com/realms/master)，Gemini 會直接將相同的「well-known」路徑附加到該子目錄，順序如下。

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (支援巢狀路徑)

必要的 JSON 功能

中繼資料回應必須包含下列欄位。如果缺少必填欄位或找不到有效類型，整合就會失敗。

authorization_endpoint

必須是有效的字串網址。

token_endpoint

必須是有效的字串網址。

response_types_supported

必須包含字串 code。

registration_endpoint

目前 Play 管理中心仍使用 Dynamic Client。

註冊 (RFC 7591)。您必須在中繼資料提供註冊端點，或直接在 Play 管理中心使用者介面輸入用戶端 ID/密鑰。

如果授權伺服器不支援 Dynamic Client Registration (DCR)，您必須手動實作並填寫 Play 管理中心使用者介面中的「用戶端 ID」和「用戶端密鑰」欄位，才能完成整合。

如果您的實作支援 Proof Key for Code Exchange (PKCE) 或永久工作階段，則必須在探索 JSON 中加入相關功能欄位 (例如驗證方法和授權類型)。確保與 Gemini 的安全性和連線能力標準相容。如果您支援範圍，則必須加入 scopes_supported 欄位。

設定範例

以下是符合客戶需求的有效 JSON 回覆。

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

如果您加入 PKCE，下列程式碼片段顯示 JSON 區塊中可能包含的內容範例。

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

如果您加入 scopes_supported 欄位，下列程式碼片段會顯示 JSON 區塊中可能包含的內容範例。

"scopes_supported": ["mcp", "cart.order"],

授權碼流程 (簡化版)

下列步驟概述標準授權碼流程。這個序列說明連結的應用程式平台如何安全地從伺服器取得必要的存取權杖，代表使用者執行操作。

1. 授權要求：Google 介面判斷需要呼叫您的函式，但使用者尚未獲得授權。聊天機器人會將使用者的瀏覽器重新導向至您的授權端點 (或顯示連結)，藉此啟動流程。

   這項要求包含您的用戶端 ID (或透過 DCR 自動產生)、Gemini 重新導向 URI，以及重要的 PKCE 參數 (code_challenge 和 code_challenge_method)。

   將下列網址加入許可清單，以便設定 OAuth：

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. 使用者同意聲明：授權伺服器會驗證要求、驗證使用者 (登入)，並要求使用者授予權限，讓 Google 介面存取其資料或服務。

3. 程式碼授權：使用者同意後，伺服器會將使用者的瀏覽器重新導向至 Gemini RedirectURI，並在網址附加暫時授權碼。

4. 權杖交換：Gemini 後端會向權杖端點傳送 POST 要求，將授權碼換成存取權杖。

   注意：這項要求必須包含 PKCE 參數 (code_verifier)，證明是同一個用戶端啟動流程。

5. 授予存取權：權杖端點會驗證授權碼和 PKCE 參數、核發存取權杖和更新權杖 (選用)，並將這些權杖傳回 Gemini。

   提示：雖然更新權杖為選用，但強烈建議您設定授權伺服器來核發。更新權杖可讓連結的應用程式平台維持存取權，不必重新驗證使用者。

PKCE 重要規定

PKCE 可多添一層安全防護，防止未經授權攔截授權碼。

注意：請務必遵守這些 PKCE 規定，才能妥善管理存取權杖和更新權杖，進而保護使用者資料，並維護生態系統的完整性。

• code_verifier：Gemini 在流程開始時產生的加密隨機字串。這項資訊不會公開。
• code_challenge：code_verifier 的轉換，通常是 SHA256 雜湊。這項資訊會公開傳送，如授權碼流程的步驟 1 所述。
• 驗證：權杖端點 (如授權碼流程步驟 4 所述) 必須驗證收到的 code_verifier 轉換後是否與原始 code_challenge 相符。

偵錯

您可以在 Logs Explorer 中查看詳細的連結錯誤資訊。如要啟用並查看錯誤，請按照「在 Google 控制台專案中監控帳戶連結錯誤」一文的指示操作。

Google 帳戶連結設定規定

請參閱下列 API 指南，瞭解 Google 帳戶連結設定。

• 使用 OAuth 連結 Google 帳戶
• 您的 Account Linking API
• Google Account Linking API

如要成功註冊 OAuth 整合，您必須設定授權伺服器的特定詳細資料。請確認您已備妥下列端點、憑證和資產。

設定欄位	說明	開發人員責任
用戶端 ID 和密鑰	授權伺服器專為連結應用程式平台產生的專屬憑證。用戶端密鑰是與用戶端 ID 相關聯的安全憑證 (密碼)。 注意：如果開發人員核發了用戶端 ID，就必須提供這項資訊。如果用戶端 ID 是由 Google 核發，開發人員可能需要註冊或驗證密鑰。	在所有授權要求中使用平台提供的 ID。
授權端點	將使用者重新導向至驗證和授權頁面的網址	託管端點，例如 https://yourdomain.com/oauth/authorize
權杖端點	後端端點，用於將授權碼換成存取/更新權杖，以及更新過期的權杖。	託管這個端點，例如 https://yourdomain.com/oauth/token
撤銷端點 選填	使用者中斷連結時，系統會透過這個網址通知您的系統撤銷權杖。 使用者在「連結的應用程式」平台取消連結或中斷連結整合功能時，我們會向 /revoke 端點發出 POST 要求，其中包含存取權杖或更新權杖。 詳情請參閱「取消連結帳戶」。	託管端點，例如 https://yourdomain.com/oauth/revoke 伺服器必須永久撤銷提供的權杖，才能處理這項要求。這樣一來，連結的應用程式平台後續嘗試使用該權杖時就會失敗，確保使用者資料安全性在取消連結後安全無虞。
重新導向 URI	平台提供的特定回呼網址，授權伺服器會在使用者同意後將授權碼傳回該網址。	設定授權伺服器，只接受平台官方註冊的重新導向 URI。
重新整理	/token (使用 grant_type=refresh_token 付款) 這項機制可讓連結的應用程式平台在目前的存取權杖到期時，取得新的存取權杖，確保整合功能順暢運作，使用者不必重複登入。 現有存取權杖到期時，連結應用程式平台會自動向您的 /token 端點發出 POST 要求。要求酬載會包含 grant_type=refresh_token，以及伺服器先前核發的更新權杖。	伺服器必須驗證提供的更新權杖，並在 JSON 回應中傳回新的存取權杖。此外，如要導入永久連結，請務必避免在交換期間輪替更新權杖。請勿核發新的更新權杖，而是在 JSON 回應中傳回完全相同的更新權杖，並在後端延長到期日。
回應類型	這項設定必須設為 CODE，才能支援授權碼流程。
範圍	一組特定權限和存取層級，定義權杖授權執行的動作。這些權限和存取層級必須在設定中預先定義，Google 才能在初始授權交握期間要求這些權限和存取層級。	您必須提供預設範圍清單 (例如 openid, profile, email)，讓連結應用程式平台在啟動流程時要求。 要求的範圍應盡可能縮減 (最小權限原則)，但必須足以支援 MCP 整合功能支援的關鍵使用者歷程 (CUJ)。
UI 素材資源：標誌	開發人員標誌，會顯示在帳戶連結和同意畫面。	必須是正方形向量圖片 (SVG)，外觀為圓形，且至少 500 x 500 像素。例如，請參閱 https://[partner-domain]/assets/logo.svg 或原始 SVG 檔案。
原生應用程式連結 (應用程式快速連結)	如要直接從原生 Android 或 iOS 應用程式支援帳戶連結，強烈建議不要使用標準網頁檢視。強烈建議您改為導入應用程式快速連結，提供流暢的使用者體驗。 詳情請參閱「透過 OAuth 應用程式快速連結功能連結 Google 帳戶」。	完成 Play 商店和應用程式商店驗證，並將 Google 的重新導向 URI 直接嵌入原生應用程式，確保應用程式對應用程式的授權切換安全無虞。
權杖有效期限	(選用) 存取權杖的有效期限，超過這個期限就必須重新整理。適合用於設定 GAL 中的逾時政策。	常見的到期時間從幾分鐘、幾小時到幾天不等，視安全性需求而定，例如 30 days)

常見整合錯誤

以下列出整合程序中常見的錯誤和可能的解決方案。

• 缺少「code」授權：Gemini 平台的自動化系統會明確檢查 response_types_supported 是否有「code」值。
• 缺少註冊端點：即使伺服器支援用戶端 ID 中繼資料文件，Gemini 應用程式 (做為連線至伺服器的 OAuth 用戶端) 目前仍需要探索 JSON 中有專屬的 registration_endpoint。
• 非 200 錯誤：如果 Gemini 的自動中繼資料探索機制存取 well-known 網址，並收到 404 或 500 錯誤，就不會嘗試猜測其他網址。請確認導覽網址可公開存取。