Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

对 AI 智能体进行身份验证

将代理部署到 Cloud Run 时，您可以为其提供身份，以便其在与 API 和其他代理通信时能够安全地进行身份验证。

向 Google Cloud API、其他代理和工具进行身份验证

如果 Cloud Run 工作负载配置为使用 agent-identity 身份类型，则会收到以下格式的系统管理型身份：

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

对于没有组织的项目，格式使用项目编号：

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

在与 Google Cloud API、其他代理或工具通信时，您可以使用此身份安全地对代理进行身份验证。

向 Google Cloud API 进行身份验证

代理可以使用其分配的代理身份向Google Cloud API（例如 Vertex AI、Cloud Storage 和其他Google Cloud 产品）进行身份验证，方法是使用从 Cloud Run 元数据服务器提取的访问令牌。

向代理的主账号授予适当的 IAM 角色，例如：
- 授予对 Vertex AI 的访问权限：
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"
```
- 授予对其他 Google Cloud API 的访问权限：
  
  向 AGENT_PRINCIPAL 授予目标资源所需的角色，例如 Cloud Storage 存储桶的 roles/storage.objectViewer。如需了解详情，请参阅使用应用默认凭证进行身份验证。
替换以下内容：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- AGENT_PRINCIPAL：代理的身份，例如 principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME。
在代理应用代码中，使用标准的 Google Cloud 客户端库。客户端库会自动使用应用默认凭证 (ADC) 从元数据服务器提取短期有效的访问令牌。

或者，您也可以手动从容器内的元数据服务器中获取访问令牌：
```
curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"
```

向 Cloud Run 上的其他代理进行身份验证

当代理需要调用 Cloud Run 上托管的其他代理（例如 A2A 代理）时，请使用由 Cloud Run 的内置 roles/run.invoker IAM 检查验证的 JSON Web 令牌 (JWT) 身份令牌进行身份验证：

在目标 Cloud Run 服务中，为调用方代理的身份授予 roles/run.invoker 角色：
```
gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION
```
替换以下内容：
- TARGET_SERVICE_NAME：目标 Cloud Run 代理服务的名称。
- CALLER_AGENT_PRINCIPAL：调用代理的身份。
- REGION：目标服务的 Google Cloud 区域。

令牌验证选项

Cloud Run 支持两种身份令牌验证方法：

无绑定令牌：由元数据服务器生成的标准受众群体绑定身份令牌。这是服务至服务和代理至代理身份验证的默认机制。
绑定令牌：使用 mTLS 在令牌和工作负载的证书之间提供加密绑定。如需使用绑定令牌，调用客户端会在请求中提供其叶证书链。

获取未绑定的 ID 令牌

从调用代理容器内，提取以目标服务的网址作为受众群体的身份令牌：
```
TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
```
将 TARGET_SERVICE_URL 替换为目标 Cloud Run 服务的网址，例如 https://target-agent-1234567890.us-central1.run.app。

向目标服务发送请求，并在 Authorization 标头中包含令牌：

curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint

获取绑定 ID 令牌 (mTLS)

从调用代理容器中读取叶证书链，并使用 POST 请求从元数据服务器请求绑定令牌：

CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")

调用目标服务的 mTLS 端点，并在 TLS 握手期间提供工作负载证书：

KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint

Python 示例

如果您编写基于 Python 的代理代码，则在存在证书的情况下，标准 Google Cloud 客户端库默认会自动请求绑定令牌。如果您需要手动发出 HTTP 请求，请执行以下操作：

import os
import requests
import google.auth
from google.auth.transport.requests import Request
from google.oauth2 import id_token

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

将 TARGET_SERVICE_MTLS_URL 替换为目标 Cloud Run 服务的 mTLS 网址，例如 https://target-agent-12345.us-central1.mtls.run.app。

对 Cloud Run 上的 MCP 服务器进行身份验证

如需连接到 Cloud Run 上托管的 MCP 服务器或工具，请使用 --functional-type=mcp-server 标识符在 Agent Registry 中自动注册 MCP 服务器。

如果您的 MCP 服务器仅由在 Cloud Run 上运行的其他代理访问，请使用内置的 IAM 调用方检查。让代理使用标准运行调用方政策进行原生通信：

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

替换以下内容：

MCP_SERVICE_NAME：托管 MCP 服务器的目标 Cloud Run 服务的名称。
CALLING_AGENT_PRINCIPAL：调用 MCP 服务器的代理的主账号身份。例如 serviceAccount:my-agent@my-project.iam.。
REGION：部署 MCP 服务器的 Google Cloud 区域。

授予 run.invoker 角色后，调用代理可以按照令牌验证选项部分中所述的方式获取身份令牌。

如需了解如何使用 IAP 保护 MCP 服务器，以实现 CLI 和程序化 SDK 访问权限，请参阅对 MCP 服务器进行身份验证。

代表用户进行身份验证

当代理代表用户访问外部工具和服务时，可以使用其预配的代理身份来管理与 MCP 服务器和外部端点的身份验证。

如需安全地处理复杂的授权工作流（例如三方 OAuth [3LO] 意见征求、双方 OAuth [2LO] 和 API 密钥），请配置 Agent Identity Auth Manager。

如需了解如何将这些授权管理器绑定到工具集，请参阅向工具和资源进行身份验证。