Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用三足式 OAuth 和驗證管理員進行驗證

如要代表特定使用者授予代理外部工具和服務 (例如 Jira 工作或 GitHub 存放區) 的存取權，請在代理身分驗證管理員中設定三足式 OAuth 驗證提供者。

三足式 OAuth 授權供應商會為您管理使用者重新導向和權杖。這樣一來，您就不必編寫自訂程式碼來處理複雜的 OAuth 2.0 流程。

三足式 OAuth 工作流程

三足式 OAuth 驗證提供者需要使用者同意，因為代理程式會代表使用者存取資源。

提示和重新導向：聊天介面會提示使用者登入，然後將使用者重新導向至第三方應用程式的同意頁面。
同意聲明和儲存：使用者授予權限後，Agent Identity 驗證管理工具會將產生的 OAuth 權杖儲存在 Google 管理的憑證保管庫中。
注入：使用 Agent Development Kit (ADK) 時，代理會自動從驗證供應商擷取權杖，並將權杖注入工具叫用標頭。

事前準備

確認您選擇的驗證方法正確無誤。
啟用 Agent Identity Connector API。
啟用 API 時所需的角色
如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API
建立及部署代理程式。
請確認您有前端應用程式，可處理使用者登入提示，並將使用者重新導向至第三方同意聲明頁面。
確認您具備完成這項工作所需的角色。

必要的角色

如要取得建立及使用三方授權供應商所需的權限，請要求管理員授予您專案的下列 IAM 角色：

如要建立驗證提供者，請按照下列步驟操作：
- IAM 連接器管理員 (roles/iamconnectors.admin)
- IAM 連接器編輯者 (roles/iamconnectors.editor)
如何使用驗證提供者：
- IAM 連接器使用者 (roles/iamconnectors.user)
- Vertex AI 使用者 (roles/aiplatform.user)
- 服務使用情形用戶 (roles/serviceusage.serviceUsageConsumer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備建立及使用三足式授權供應商所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立及使用三足式驗證供應商，必須具備下列權限：

如要建立驗證提供者： iamconnectors.connectors.create
如何使用驗證提供者：
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

建立三方驗證提供者

建立驗證提供者，定義第三方應用程式的設定和憑證。

如要建立三方授權供應商，請使用 Google Cloud 控制台或 Google Cloud CLI。

控制台

前往 Google Cloud 控制台的「Agent Registry」頁面。
前往 Agent Registry
按一下要建立驗證提供者的代理程式名稱。
按一下「身分」。
在「Auth Providers」(驗證提供者) 專區中，按一下「新增驗證提供者」。
在「新增驗證供應商」窗格中，輸入名稱和說明。

名稱只能使用小寫英文字母、數字或連字號，開頭須為小寫英文字母，結尾不得為連字號。
在「OAuth Type」(OAuth 類型) 清單中，選取「OAuth (3 legged)」(OAuth (三足式))。 .
點按「Create and continue」(建立並繼續)。
如要授予代理程式身分使用驗證提供者的權限，請按一下「授予存取權」。
這會自動將「連結器使用者」(roles/iamconnectors.user) 角色指派給授權提供者資源上的代理程式身分。
複製回呼網址。
在另一個分頁中，在第三方 OAuth 用戶端應用程式中註冊回呼網址。
在「Auth provider credentials」(驗證供應商憑證) 專區中，輸入下列資訊：
- 用戶端 ID
- 用戶端密碼
- 權杖網址
- 授權網址
按一下「新增供應商設定」。

新建立的驗證供應商會顯示在「驗證供應商」清單中。

gcloud CLI

設定 OAuth 用戶端應用程式，註冊用戶端並取得用戶端 ID 和用戶端密鑰。使用該節中的範本指定重新導向 URI。

使用用戶端憑證建立驗證供應商：

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"

確認驗證供應商顯示在清單中，且狀態為 ENABLED：

gcloud alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

授予存取權，允許代理程式和本機開發環境從驗證提供者擷取憑證。如要允許已部署的代理程式和個人使用者帳戶存取驗證供應商，請在驗證供應商資源上授予「連結器使用者」(roles/iamconnectors.user) 角色：

授予已部署代理程式的 SPIFFE ID (代理程式身分) 存取權：

gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

授予個人使用者帳戶存取權，以進行本機開發和測試 (adk web)：

gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.user" \
    --member="user:USER_EMAIL"

更改下列內容：

PROJECT_ID： Google Cloud 專案 ID。
LOCATION：部署驗證供應商和代理程式的位置 (例如 us-west1)。
AUTH_PROVIDER_NAME：驗證供應商的名稱 (例如 bigquery-mcp-3lo-authprovider)。
AUTHORIZATION_URL：授權伺服器網址 (例如 https://accounts.google.com/o/oauth2/v2/auth)。
TOKEN_URL：權杖伺服器網址 (例如 https://oauth2.googleapis.com/token)。
CLIENT_ID：您從第三方服務產生的 OAuth 用戶端 ID。
CLIENT_SECRET：您從第三方服務產生的 OAuth 用戶端密鑰。
ORGANIZATION_ID：您的 Google Cloud 機構 ID。
PROJECT_NUMBER：您的 Google Cloud 專案編號。
ENGINE_ID：已部署的推論引擎代理程式 ID。
USER_EMAIL：您的個人使用者帳戶電子郵件地址。

設定 OAuth 用戶端應用程式

註冊 OAuth 用戶端憑證之前，請先從第三方授權伺服器 (例如 Google、GitHub 或 Jira) 取得用戶端 ID 和用戶端密鑰。

如要連線至Google Cloud以外的第三方服務，請從該服務的開發人員入口網站取得 OAuth 用戶端憑證，並略過本節中的步驟。

註冊重新導向 URI

設定 OAuth 用戶端憑證時，請務必註冊驗證供應商的專屬回呼重新導向 URI。

使用下列範本建構重新導向 URI：

https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallback

更改下列內容：
- PROJECT_ID： Google Cloud 專案 ID。
- LOCATION: The region where your auth provider will be deployed (for example,us-west1`).
- CONNECTOR_NAME：驗證供應商的名稱。
例如：https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallback
如要連線至 Google Cloud 服務 (例如 BigQuery)，您可以在 Google Cloud 控制台中設定同意畫面，並建立 OAuth 用戶端憑證：
1. 設定 OAuth 同意畫面：
  1. 在 Google Cloud 控制台中，前往「APIs & Services」(API 和服務) >「OAuth consent screen」(OAuth 同意畫面) 頁面。
    依序前往「APIs & Services」(API 和服務)>「OAuth consent screen」(OAuth 同意畫面)
  2. 在「應用程式資訊」部分，輸入應用程式名稱 (例如 BigQuery 管理員應用程式) 和支援電子郵件地址。
  3. 在「目標對象」部分，選取「內部」或「外部」。
  4. 輸入聯絡資訊，即可接收通知。
  5. 詳閱並接受《Google API 服務使用者資料政策》。
  6. 按一下「完成」。
2. 建立 OAuth 用戶端憑證：
  1. 在 Google Cloud 控制台中，依序前往「API 和服務」 >「OAuth 同意畫面」 >「用戶端」頁面。
    依序前往「APIs & Services」(API 和服務) >「OAuth consent screen」(OAuth 同意畫面) >「Clients」(用戶端)
  2. 依序點選「建立憑證」>「OAuth 用戶端 ID」。
  3. 從清單中選取「網頁應用程式」選項。
  4. 為 OAuth 用戶端輸入容易辨識的名稱。
  5. 在「已授權的重新導向 URI」部分，按一下「新增 URI」，然後輸入您建構的重新導向 URI。
  6. 點選「建立」。在「OAuth client created」(已建立 OAuth 用戶端) 對話方塊中，複製產生的「Client ID」(用戶端 ID) 和「Client Secret」(用戶端密碼) 值。

在代理程式碼中進行驗證

如要驗證代理程式，可以使用 ADK 或直接呼叫 Agent Identity API。

ADK

使用 ADK 中的 MCP 工具集，在代理的程式碼中參照驗證提供者。

from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register the Google Cloud Auth Provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create the Auth Provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

範例：連結至 BigQuery MCP

以下範例顯示 agent.py 設定，可使用 3 向 OAuth 將代理程式連線至 BigQuery MCP 伺服器：

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager