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

如需让您的智能体使用自己的授权向 ServiceNow 或 Salesforce 等外部工具进行身份验证，请在 Agent Identity 身份验证管理器中使用 2-legged OAuth（客户端凭据）身份验证提供方配置出站身份验证。

通过管理凭证和令牌，双向 OAuth 身份验证提供方无需使用自定义代码来处理身份验证流程。

重要提示：本文档介绍了如何使用 Agent Identity API 进行身份验证。我们建议您使用 Agent Identity API，因为 IAM Connectors API（预览版）不会正式发布。如果您使用的是 IAM Connectors API，请迁移到 Agent Identity API。

两方模式 OAuth 工作流

2-legged OAuth 身份验证提供方使用代理的身份，不需要用户同意。Google 负责管理客户端凭证的存储。当您使用智能体开发套件 (ADK) 时，它会自动检索生成的访问令牌并将其注入到工具调用标头中。

准备工作

1. 验证您是否选择了正确的身份验证方法。

2. 启用 Agent Identity API（如果尚未启用）。

   启用 API 所需的角色

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

   启用 API

3. 创建和部署代理。

4. 从要连接到的第三方应用获取客户端 ID 和客户端密钥。

5. 验证您是否拥有完成此任务所需的角色。

所需的角色

如需获得创建和使用 2-legged Agent Identity 身份验证提供方所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

• 如需创建身份验证提供方，请执行以下操作：
  • Agent Identity Admin (roles/agentidentity.admin)
  • Agent Identity Editor (roles/agentidentity.editor)
• 如需使用身份验证提供方，请执行以下操作：
  • Agent Identity User (roles/agentidentity.user)
  • Agent Default Access (roles/aiplatform.agentDefaultAccess)
  • Agent Context Editor (roles/aiplatform.agentContextEditor)
  • Vertex AI User (roles/aiplatform.user)
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

这些预定义角色包含创建和使用 2-legged 代理身份验证提供方所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建和使用 2-legged 代理身份验证提供方，您需要具备以下权限：

• 如需创建身份验证提供方，请执行以下操作： agentidentity.authProviders.create
• 如需使用身份验证提供方，请执行以下操作：
  • agentidentity.authProviders.retrieveCredentials
  • aiplatform.endpoints.predict
  • aiplatform.sessions.create

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

创建 2-legged 身份验证提供方

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

如需创建 2-legged 身份验证提供方，请使用 Google Cloud 控制台、Google Cloud CLI 或 REST API。

控制台

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

   前往 Agent Registry

2. 点击要为其创建身份验证提供方的代理的名称。
3. 点击身份。
4. 在身份验证提供方部分中，点击 添加身份验证提供方。

5. 在添加身份验证提供方窗格中，输入名称和说明。

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

6. 从 OAuth Type（OAuth 类型）列表中，选择 OAuth (2 legged)（OAuth [两方模式]）。
7. 点击创建并继续。
8. 如需向您的智能体身份授予使用身份验证提供方的权限，请点击授予访问权限。

   此过程会自动将代理身份用户 (roles/agentidentity.user) 角色分配给身份验证提供方资源上的代理身份。

9. 在Auth 提供方凭证部分中，输入以下信息：
   • 客户端 ID (Client ID)
   • 客户端密钥 (Client Secret)
   • 令牌网址
10. 点击添加提供商配置。

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

gcloud CLI

1. 创建身份验证提供方：

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --location="LOCATION" \
       --two-legged-oauth-client-id="CLIENT_ID" \
       --two-legged-oauth-client-secret="CLIENT_SECRET" \
       --two-legged-oauth-token-url="TOKEN_URL"

2. 验证您的身份验证提供方是否显示在列表中，并且其状态为 ENABLED：

   gcloud agent-identity auth-providers list \
      --project="PROJECT_ID" \
      --location="LOCATION"

3. 授予访问权限，以便您的代理和本地开发环境能够从身份验证提供方检索凭证。如需允许已部署的代理和您的个人用户账号访问身份验证提供方，请针对身份验证提供方资源授予 Agent Identity User (roles/agentidentity.user) 角色：

   1. 向已部署智能体的 SPIFFE ID（智能体身份）授予访问权限：

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.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 agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="user:USER_EMAIL"

替换以下内容：

• PROJECT_ID：您的 Google Cloud 项目 ID。
• LOCATION：身份验证提供方和代理的部署位置（例如 us-west1）。
• AUTH_PROVIDER_NAME：身份验证提供方的名称（例如 jira-mcp-2lo-authprovider）。
• CLIENT_ID：您从第三方服务生成的 OAuth 客户端 ID。
• CLIENT_SECRET：您从第三方服务生成的 OAuth 客户端密钥。
• TOKEN_URL：令牌服务器网址（例如 https://oauth2.googleapis.com/token）。
• ORGANIZATION_ID：您的 Google Cloud 组织 ID。
• PROJECT_NUMBER：您的 Google Cloud 项目编号。
• ENGINE_ID：已部署的推理引擎智能体的 ID。
• USER_EMAIL：您的个人用户账号邮箱。

REST

1. 创建身份验证提供方：

   Agent Identity API 的 authProviders.create 方法在项目和位置中创建双向 OAuth 身份验证提供方。

   在使用任何请求数据之前，请先进行以下替换：

   • PROJECT_ID：您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串，例如 my-project。
   • LOCATION：身份验证提供方和代理的部署位置（例如 us-west1）。
   • AUTH_PROVIDER_NAME：身份验证提供方的名称（例如 jira-mcp-2lo-authprovider）。该名称只能包含小写字母、数字或连字符，不能以连字符结尾，且必须以小写字母开头。
   • CLIENT_ID：您从第三方服务生成的 OAuth 客户端 ID。
   • CLIENT_SECRET：您从第三方服务生成的 OAuth 客户端密钥。
   • TOKEN_URL：令牌服务器网址（例如 https://oauth2.googleapis.com/token）。

   HTTP 方法和网址：

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

   请求 JSON 正文：

   {
     "authProviderTypeParams": {
       "twoLeggedOauth": {
         "clientId": "CLIENT_ID",
         "clientSecret": "CLIENT_SECRET",
         "tokenUrl": "TOKEN_URL"
       }
     }
   }
   

   如需发送您的请求，请展开以下选项之一：

   curl（Linux、macOS 或 Cloud Shell）

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME"

   PowerShell (Windows)

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME" | Select-Object -Expand Content

   APIs Explorer（浏览器）

   复制请求正文并打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。 将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

   您应该收到类似以下内容的 JSON 响应：

   {
     "name": "projects/my-project/locations/us-west1/authProviders/jira-mcp-2lo-authprovider",
     "createTime": "2026-04-03T21:15:41.367155Z",
     "updateTime": "2026-04-03T21:15:41.367155Z",
     "authProviderTypeParams": {
       "twoLeggedOauth": {
         "clientId": "my-oauth-client-id",
         "tokenUrl": "https://oauth2.googleapis.com/token"
       }
     },
     "state": "ENABLED"
   }
   

2. 如需允许已部署的代理和您的个人用户账号从身份验证提供方检索凭据，请向身份验证提供方资源授予 Agent Identity User (roles/agentidentity.user) 角色：

   Agent Identity API 的 authProviders.setIamPolicy 方法可对身份验证提供方资源设置允许政策。

   在使用任何请求数据之前，请先进行以下替换：

   • PROJECT_ID：您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串，例如 my-project。
   • LOCATION：身份验证提供方和代理的部署位置（例如 us-west1）。
   • AUTH_PROVIDER_NAME：身份验证提供方的名称。
   • ORGANIZATION_ID：您的 Google Cloud组织 ID。
   • PROJECT_NUMBER：部署了代理的项目的数字 Google Cloud 项目编号（例如 987654321098）。
   • ENGINE_ID：已部署的推理引擎代理的 ID。
   • USER_EMAIL：您的个人用户账号邮箱。

   HTTP 方法和网址：

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

   请求 JSON 正文：

   {
     "policy": {
       "bindings": [
         {
           "role": "roles/agentidentity.user",
           "members": [
             "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
             "user:USER_EMAIL"
           ]
         }
       ]
     }
   }
   

   如需发送您的请求，请展开以下选项之一：

   curl（Linux、macOS 或 Cloud Shell）

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy"

   PowerShell (Windows)

   注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

   将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy" | Select-Object -Expand Content

   APIs Explorer（浏览器）

   复制请求正文并打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。 将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

   您应该收到类似以下内容的 JSON 响应：

   {
     "version": 1,
     "etag": "BwYKmjvelug=",
     "bindings": [
       {
         "role": "roles/agentidentity.user",
         "members": [
           "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
           "user:[e-mail]"
         ]
       }
     ]
   }
   

在代理代码中进行身份验证

如需对智能体进行身份验证，您可以使用 ADK。

注意：以下示例在模块级注册身份验证提供方，这在您本地运行智能体或使用 Agents CLI 部署智能体时有效。如果您使用 Vertex AI Python SDK 进行部署，请改为在 set_up() 中注册身份验证提供方，以便其在已部署的容器中运行。如需了解详情，请参阅部署代理。

ADK

使用 ADK 中的 MCP 工具集在代理的代码中引用身份验证提供方。

from google.adk.agents import Agent
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())

# Create the Google Cloud Auth Provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

# 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 = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

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

import httpx
from google.adk.agents import Agent
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())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/authProviders/"
            "AUTH_PROVIDER_NAME"
        )
    )
)

# 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 = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    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 工具集在代理的代码中引用身份验证提供方。

您无需为此流程构建身份验证方案。MCP 服务器的出站绑定已记录要使用的身份验证提供方。

注意：请为身份验证提供方、MCP 服务器和 Agent Registry 客户端使用同一区域。global 位置不提供身份验证提供方，因此如果您设置 location="global"，则创建出站绑定会失败，并显示错误 Location of auth provider does not match location of binding。

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

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

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

  

安装依赖项以进行本地测试

如需在虚拟环境中本地测试智能体，请安装以下必要的依赖项：

1. 创建并激活虚拟环境：

   python3 -m venv env
   source env/bin/activate

2. 安装所需的软件包：

   pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

部署智能体

将智能体部署到 Google Cloud时，请确保已启用智能体身份。

Agent CLI

如果您使用的是智能体开发套件 (ADK) 和 Agent CLI，请按照以下步骤部署启用了智能体身份的智能体：

1. 在代理应用文件夹中，创建一个名为 .agent_engine_config.json 的配置文件，以启用代理身份：

   echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

2. 将智能体部署到 Gemini Enterprise Agent Platform 上的 Agent Runtime：

   uv run adk deploy agent_engine AGENT_NAME \
       --project="PROJECT_ID" \
       --region="LOCATION"

   替换以下内容：

   • AGENT_NAME：智能体应用文件夹的名称（例如 maps_agent）。
   • PROJECT_ID：您的 Google Cloud项目 ID。
   • LOCATION：您要在其中部署智能体的受支持区域（例如 us-west1）。

Python SDK

如果您使用 Vertex AI Python SDK 以编程方式进行部署，请使用 identity_type=AGENT_IDENTITY 标志：

注意：SDK 会序列化您的应用对象，因此本地脚本在导入时运行的 CredentialManager.register_auth_provider() 调用不会在已部署的容器中运行。而是在应用的 set_up() 方法中注册身份验证提供方，运行时会在容器启动时调用该方法。 否则，智能体在查询时会失败，并显示 No auth provider registered for custom auth scheme 'gcpAuthProviderScheme'。如需了解详情，请参阅部署注意事项。

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

替换以下内容：

• PROJECT_ID：您的 Google Cloud 项目 ID。
• LOCATION：您要在其中部署智能体的受支持区域（例如 us-west1）。

后续步骤

• 代理身份概览
• 使用三方模式 OAuth 通过身份验证管理器进行身份验证
• 使用 API 密钥通过身份验证管理器进行身份验证
• 管理 Agent Identity 身份验证提供方
• 排查 Agent Identity 身份验证管理器问题