使用三方模式 OAuth 和身份验证管理器进行身份验证

如需代表特定最终用户向您的智能体授予对外部工具和服务的访问权限(例如 Jira 任务或 GitHub 代码库),请在 Agent Identity Auth Manager 中配置三方模式 OAuth 身份验证提供方。

三方模式 OAuth 身份验证提供方会为您管理用户重定向和令牌。这样一来,您就无需编写自定义代码来处理复杂 OAuth 2.0 流程。

三方模式 OAuth 工作流

三方模式 OAuth 身份验证提供方需要用户同意,因为智能体会代表用户访问资源。

  1. 提示和重定向:聊天界面会提示用户登录 然后将用户重定向到第三方应用的同意页面。
  2. 同意和存储:用户授予权限后,Agent Identity Auth Manager 会将生成的 OAuth 令牌存储在 Google 管理的凭据保险库中。
  3. 注入:使用智能体开发套件 (ADK) 时,智能体会自动从身份验证提供方检索令牌,并将其注入到工具调用标头中。

准备工作

  1. 确认您已选择正确的身份验证方法
  2. 启用 Agent Identity Connector API。

    启用 API 所需的角色

    如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您 创建了项目,则可能已通过 所有者角色 (roles/owner) 拥有此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色

    启用 API

  3. 创建和部署 智能体
  4. 确保您有一个前端应用来处理用户登录提示 和重定向到第三方同意页面。
  5. 确认您拥有完成 此任务所需的角色。

所需的角色

如需获得创建和使用三方模式身份验证提供方所需的权限,请让您的管理员为您授予项目的以下 IAM 角色:

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限

这些预定义角色包含 创建和使用三方模式身份验证提供方所需的权限。如需查看所需的确切权限,请展开所需权限部分:

所需权限

创建和使用三方模式身份验证提供方需要以下权限:

  • 如需创建身份验证提供方: iamconnectors.connectors.create
  • 如需使用身份验证提供方:
    • iamconnectors.connectors.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

您也可以使用自定义角色或其他预定义角色来获取这些权限。

创建三方模式身份验证提供方

创建身份验证提供方,以定义第三方应用的配置和凭据。

如需创建三方模式身份验证提供方,请使用 Google Cloud 控制台或 Google Cloud CLI。

控制台

  1. 在 Google Cloud 控制台中,前往 Agent Registry 页面。

    前往 Agent Registry

  2. 点击要为其创建身份验证提供方的智能体的名称。
  3. 点击身份
  4. Auth Providers 部分中,点击 Add auth provider
  5. Add auth provider 窗格中,输入名称和说明。

    名称只能包含小写字母、数字或连字符,不能以连字符结尾,并且必须以小写字母开头。

  6. OAuth Type 列表中,选择 OAuth (3 legged)
  7. 点击创建并继续
  8. 如需向您的智能体身份授予使用身份验证提供方的权限,请点击授予访问权限

    这会自动将 Connector User (roles/iamconnectors.user) 角色分配给 身份验证提供方资源上的智能体身份。

  9. 复制回调网址。
  10. 在单独的标签页中,在第三方 OAuth 客户端应用中注册回调网址
  11. Auth provider credentials 部分中,输入以下信息:
    • 客户端 ID
    • 客户端密钥
    • 令牌网址
    • 授权网址
  12. 点击 Add provider config

新创建的身份验证提供方会显示在 Auth Providers 列表中。

gcloud CLI

  1. 配置 OAuth 客户端 应用以注册客户端并获取客户端 ID 和 客户端密钥。使用该部分中的模板指定重定向 URI。

  2. 使用客户端凭据创建身份验证提供方:

    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"
  3. 验证您的身份验证提供方是否显示在列表中,并且其状态为 ENABLED
    gcloud alpha agent-identity connectors list \
       --project="PROJECT_ID" \
       --location="LOCATION"
  4. 授予访问权限,以允许您的智能体和本地开发 环境从身份验证提供方检索凭据。如需允许 已部署的智能体和您的个人用户账号访问身份验证 提供方,请在身份验证提供方 资源上授予 Connector User (roles/iamconnectors.user) 角色:

    1. 向已部署的智能体的 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"
    2. 向您的个人用户账号授予访问权限,以进行本地开发和测试 (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。

  1. 使用以下模板构建重定向 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

  2. 如果您要连接到 Google Cloud 服务(例如 BigQuery),则可以在 Google Cloud 控制台中配置权限请求页面并创建 OAuth 客户端凭据:

    1. 配置 OAuth 权限请求页面:

      1. 在 Google Cloud 控制台中,前往 APIs & Services >OAuth 权限请求页面 页面。

        前往 APIs & Services >OAuth 权限请求页面

      2. App information 部分中,输入应用名称 (例如 BigQuery Manager Application)和 支持电子邮件地址。
      3. Audience 部分中,选择 InternalExternal
      4. 输入您的联系信息以接收通知。
      5. 阅读并接受 Google API Services User Data Policy
      6. 点击完成
    2. 创建 OAuth 客户端凭据:

      1. 在 Google Cloud 控制台中,前往 APIs & Services >OAuth consent screen >Clients 页面。

        前往 APIs & Services >OAuth 权限请求页面 >客户端

      2. 点击创建凭据 >OAuth 客户端 ID
      3. 从列表中选择 Web 应用 选项。
      4. 为您的 OAuth 客户端输入一个可识别的名称。
      5. Authorized redirect URIs 部分中,点击 Add URI ,然后输入您构建的重定向 URI。
      6. 点击创建 。在 OAuth 客户端已创建 对话框中,复制生成的 客户端 ID客户端密钥 值。

在智能体代码中进行身份验证

如需对智能体进行身份验证,您可以使用 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

以下示例展示了使用三方模式 OAuth 将智能体连接到 BigQuery MCP 服务器的 agent.py 配置:

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
import google.auth
from google.genai import types

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME"
bigquery_mcp_endpoint = os.environ.get(
    "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp"
)

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the callback is received.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/connectors/{bigquery_mcp_auth_provider_id}",
    scopes=["https://www.googleapis.com/auth/bigquery"],
    continue_uri=CONTINUE_URI,
)

bigquery_mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint),
    auth_scheme=bigquery_mcp_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful"
        " information. You can also use your BigQuery MCP tools to look up"
        " BigQuery data."
    ),
    tools=[bigquery_mcp_tools],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

使用 ADK 中的经过身份验证的函数工具在智能体的代码中引用身份验证提供方。

import httpx
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

使用 ADK 中的 Agent Registry 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
from google.adk.integrations.agent_identity import 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
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider by providing auth provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(
    mcp_server_name="projects/PROJECT_ID/locations/"
    "global/mcpServers/"
    "agentregistry-00000000-0000-0000-0000-000000000000",