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

配置 IAM 代理政策

您可以创建政策来管理代理与服务之间的通信。Agent Gateway 使用 Identity-Aware Proxy (IAP) 来强制执行政策。

您可以使用 Google Cloud 控制台中的政策页面创建 Agent Gateway IAM 允许政策。

您可以使用 Google Cloud CLI 创建 IAM 允许政策和拒绝政策。

准备工作

在创建 IAM 允许政策之前：

设置 Google Cloud 结算项目。
了解您要从中管理访问权限的代理的身份。如需使用 Google Cloud 控制台管理整个注册表的访问权限，请选择包含该注册表的项目。
- Agent Platform 和 Gemini Enterprise 智能体：了解智能体身份。
- DIY 代理（Cloud Run）：了解基于服务账号的身份。
您要管理其访问权限的目标代理资源（代理、MCP 服务器和端点）必须在 Agent Registry 中注册。
设置 Agent Gateway。建议您先在试运行模式下配置 Agent Gateway。如需了解 Agent Gateway，请参阅Agent Gateway 概览。

所需的角色

如需获得为 AI 代理配置代理平台所需的权限，请让管理员向您授予项目的以下 IAM 角色：

IAP Policy Admin (roles/iap.admin)
Agent Registry Viewer (roles/agentregistry.viewer)
Project IAM Admin (roles/resourcemanager.projectIamAdmin)
Network Security Admin (roles/networksecurity.admin)
Service Extensions Admin (roles/serviceextensions.admin)

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

使用 IAP 创建 IAM 允许政策

您可以为以下类型的代理互动定义出站政策：

代理到注册表
智能体到智能体
代理到 MCP 服务器
智能体到端点

创建代理到注册表的政策

通过代理到注册表的政策，您的代理可以访问当前项目中的代理注册表中的所有代理、MCP 服务器和端点。

控制台

Google Cloud 控制台中，执行以下操作：

选择源代理和目标注册表。
1. 在 Google Cloud 控制台中，前往政策页面：
  
  前往“政策”
2. 如需为 Agent Gateway 出站流量添加 IAM 允许政策，请点击 Add IAM policy。
3. 如需选择源代理，请执行以下操作：
  - 如需选择代理注册表中当前所选项目中的所有代理，请选择所有代理。
  - 如需选择当前项目中的特定代理，请执行以下操作：
    - 选择个人代理。如需查找代理，请使用过滤条件 Filter 字段进行搜索。
    - 选择要授予访问权限的源代理。
    - 如需选择代理，请点击确定。
4. 在访问目标中，点击注册表。
5. 如需创建 IAM 允许政策并将其绑定到注册表，请点击创建。
如需创建条件，请执行以下操作：
1. 在条件中，点击添加条件。
2. 在添加条件对话框中，执行以下操作：
  1. 在名称中，输入条件的名称。
  2. 在说明中，输入条件的说明。
  3. 如需使用条件构建器添加条件，请执行以下操作：
    1. 在条件类型中，从以下选项中选择条件类型：
      - 名称：根据所访问资源的名称限制代理访问权限。
      - ReadOnly：代理访问权限是否仅限于读取数据，这会阻止代理执行写入操作。
      - 破坏性：代理是否可以执行被认为有害或不可逆的操作，例如删除资源。
      - 幂等：是否可以替换代理访问权限。
      - 开放世界：智能体是否可以与外部实体的“开放世界”（例如，网络搜索工具）互动。如果您将此条件设置为 `false`，则表示代理互动已结束。
    2. 在运算符中，选择布尔运算符。
    3. 在值中，选择条件的值。
    4. 如需添加其他条件，请点击添加其他条件。
    5. 如需保存条件，请点击保存。
  4. 如需使用条件编辑器添加条件，请在文本字段中输入 CEL 表达式。

gcloud

如需使用 gcloud CLI 创建从代理到注册表的出站流量政策，请执行以下操作：

创建包含 IAM 政策的 IAP 政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ],
        "condition": {
          CONDITION
        }

      }
    ]
  }
}
```
替换以下内容：
- AGENT_PRINCIPAL：源代理身份的主账号，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER - 例如，principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - DIY 代理：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如，principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
- CONDITION：
  条件参数，格式如下：
```
"condition": {
  "title": "CONDITION_TITLE",
  "description": "CONDITION_DESCRIPTION",
  "expression": "CEL_EXPRESSION"
}
```
  替换以下内容：
  - CONDITION_TITLE：条件的标题
  - CONDITION_DESCRIPTION：条件的说明
  - CEL_EXPRESSION：条件表达式。此表达式必须是有效的 CEL 表达式。它必须评估为 True 才能允许访问。

在 IAP 中为代理注册表中的所有资源设置 IAM 允许政策：

gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --resource-type=AgentRegistry \
    --region=REGION

替换以下内容：

PROJECT_ID：包含资源的项目的项目 ID。或者，您也可以分别指定 --folder 或 --organization 标志，将政策绑定到文件夹或组织。
REGION：资源所在的区域

以下示例展示了代理层次结构的出口访问权限：

{
"policy": {
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/1234"
      ]
    }
  ]
}
}

创建代理到代理的出站流量政策

控制台

如需使用 Google Cloud 控制台定义代理到代理的出站流量政策，请执行以下操作：

在 Google Cloud 控制台中，前往政策页面：

前往“政策”
如需为 Agent Gateway 出站流量添加 IAM 允许政策，请点击 Add IAM policy。
如需选择源代理，请执行以下操作：
- 如需选择代理注册表中当前所选项目中的所有代理，请选择所有代理。
- 如需选择当前项目中的特定代理，请执行以下操作：
  - 选择个人代理。如需查找代理，请使用过滤条件 Filter 字段进行搜索。
  - 选择要授予访问权限的源代理。
  - 如需选择代理，请点击确定。
在访问目标中，点击代理。
在选择代理中，选择您希望源代理访问的目标代理。如需查找代理，请使用过滤条件 过滤条件字段进行搜索。
如需创建 IAM 允许政策并将其绑定到代理，请点击创建。

gcloud

在 JSON 格式的文件中创建 IAM 允许政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ]
      }
    ]
  }
}
```
替换以下内容：
- AGENT_PRINCIPAL：源代理身份的主账号，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER - 例如，principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - DIY 代理：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如，principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
将 IAM 政策绑定到 IAP。
```
gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --agent=AGENT_ID \
    --region=REGION
```
替换以下内容：
- PROJECT_ID：包含资源的项目的项目 ID。或者，您也可以分别指定 --folder 或 --organization 标志，将政策绑定到文件夹或组织。
- AGENT_ID：代理的 ID
- REGION：资源所在的区域

创建代理到 MCP 服务器的出站政策

控制台

如需使用 Google Cloud 控制台定义从代理到 MCP 服务器的出站流量政策，请执行以下操作：

在 Google Cloud 控制台中，前往政策页面：

前往“政策”
如需为 Agent Gateway 出站流量添加 IAM 允许政策，请点击 Add IAM policy。
如需选择源代理，请执行以下操作：
- 如需选择代理注册表中当前所选项目中的所有代理，请选择所有代理。
- 如需选择当前项目中的特定代理，请执行以下操作：
  - 选择个人代理。如需查找代理，请使用过滤条件 Filter 字段进行搜索。
  - 选择要授予访问权限的源代理。
  - 如需选择代理，请点击确定。
在访问目标中，点击 MCP 服务器。
在 Select MCP server 中，选择您希望源代理访问的目标 MCP 服务器。如需查找 MCP 服务器，请使用过滤条件 Filter 字段进行搜索。
如需创建 IAM 允许政策并将其绑定到 MCP 服务器，请点击创建。

创建条件：
1. 在条件中，点击添加条件。
2. 在添加条件对话框中，执行以下操作：
  1. 在名称中，输入条件的名称。
  2. 在说明中，输入条件的说明。
  3. 如需使用条件构建器添加条件，请执行以下操作：
    1. 在条件类型中，从以下选项中选择条件类型：
      - 名称：根据所访问资源的名称限制代理访问权限。
      - ReadOnly：代理访问权限是否仅限于读取数据，这会阻止代理执行写入操作。
      - 破坏性：代理是否可以执行被认为有害或不可逆的操作，例如删除资源。
      - 幂等：是否可以替换代理访问权限。
      - 开放世界：智能体是否可以与外部实体的“开放世界”（例如，网络搜索工具）互动。如果您将此条件设置为 `false`，则表示代理互动已结束。
    2. 在运算符中，选择布尔运算符。
    3. 在值中，选择条件的值。
    4. 如需添加其他条件，请点击添加其他条件。
    5. 如需保存条件，请点击保存。
  4. 如需使用条件编辑器添加条件，请在文本字段中输入 CEL 表达式。

gcloud

如需使用 gcloud CLI 创建从代理到 MCP 服务器的出站流量政策，请执行以下操作：

包括：在 JSON 格式的文件中创建 IAM 允许政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ],
        "condition": {
          CONDITION
        }

      }
    ]
  }
}
```
替换以下内容：
- AGENT_PRINCIPAL：源代理身份的主账号，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER - 例如，principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - DIY 代理：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如，principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
- CONDITION：
  条件参数，格式如下：
```
"condition": {
  "title": "CONDITION_TITLE",
  "description": "CONDITION_DESCRIPTION",
  "expression": "CEL_EXPRESSION"
}
```
  替换以下内容：
  - CONDITION_TITLE：条件的标题
  - CONDITION_DESCRIPTION：条件的说明
  - CEL_EXPRESSION：条件表达式。此表达式必须是有效的 CEL 表达式。它必须评估为 True 才能允许访问。

将 IAM 政策绑定到 IAP。

gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --mcpServer=MCP_SERVER_ID 
    --region=REGION

替换以下内容：

PROJECT_ID：包含资源的项目的项目 ID。或者，您也可以分别指定 --folder 或 --organization 标志，将政策绑定到文件夹或组织。
MCP_SERVER_ID：MCP 服务器的 ID
REGION：资源所在的区域

以下示例展示了一项 IAM 允许政策，该政策允许 DIY 代理使用 MCP 授权类型对名为 GitHubTool 的工具进行只读访问。

{
"policy": {
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-pool.svc.id.goog/subject/ns/default/sa/my-ae-agent"
      ],
      "condition": {
        "title": "Allow AE Agent Read-Only Egress to GitHub MCP server",
        "expression": "api.getAttribute('iap.googleapis.com/mcp.toolName', '') == 'GitHubTool' && api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true && api.getAttribute('iap.googleapis.com/request.auth.type', '') == 'MCP'"
      }
    }
  ]
}
}

创建从代理到端点的出站流量政策

控制台

如需使用 Google Cloud 控制台定义代理到端点的出站流量政策，请执行以下操作：

在 Google Cloud 控制台中，前往政策页面：

前往“政策”
如需为 Agent Gateway 出站流量添加 IAM 允许政策，请点击 Add IAM policy。
如需选择源代理，请执行以下操作：
- 如需选择代理注册表中当前所选项目中的所有代理，请选择所有代理。
- 如需选择当前项目中的特定代理，请执行以下操作：
  - 选择个人代理。如需查找代理，请使用过滤条件 Filter 字段进行搜索。
  - 选择要授予访问权限的源代理。
  - 如需选择代理，请点击确定。
在访问目标中，点击端点。
在选择端点中，选择您希望源代理访问的目标端点。如需查找端点，请使用过滤条件过滤字段进行搜索。
如需创建 IAM 允许政策并将其绑定到端点，请点击创建。

创建条件：
1. 在条件中，点击添加条件。
2. 在添加条件对话框中，执行以下操作：
  1. 在名称中，输入条件的名称。
  2. 在说明中，输入条件的说明。
  3. 如需使用条件构建器添加条件，请执行以下操作：
    1. 在条件类型中，从以下选项中选择条件类型：
      - 名称：根据所访问资源的名称限制代理访问权限。
      - ReadOnly：代理访问权限是否仅限于读取数据，这会阻止代理执行写入操作。
      - 破坏性：代理是否可以执行被认为有害或不可逆的操作，例如删除资源。
      - 幂等：是否可以替换代理访问权限。
      - 开放世界：智能体是否可以与外部实体的“开放世界”（例如，网络搜索工具）互动。如果您将此条件设置为 `false`，则表示代理互动已结束。
    2. 在运算符中，选择布尔运算符。
    3. 在值中，选择条件的值。
    4. 如需添加其他条件，请点击添加其他条件。
    5. 如需保存条件，请点击保存。
  4. 如需使用条件编辑器添加条件，请在文本字段中输入 CEL 表达式。

gcloud

包括：在 JSON 格式的文件中创建 IAM 允许政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ]
      }
    ]
  }
}
```
替换以下内容：
- AGENT_PRINCIPAL：源代理身份的主账号，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER - 例如，principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - DIY 代理：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如，principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
将 IAM 政策绑定到 IAP。
```
gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --endpoint=ENDPOINT_ID \
    --region=REGION
```
替换以下内容：
- PROJECT_ID：包含资源的项目的项目 ID。或者，您也可以分别指定 --folder 或 --organization 标志，将政策绑定到文件夹或组织。
- ENDPOINT_ID：端点的 ID
- REGION：资源所在的区域

使用 IAP 对 Cloud Run MCP 服务器进行身份验证

如需为部署在 Cloud Run 上的 MCP 服务器配置基于 IAP 的身份验证，请执行以下操作：

在 Cloud Run 上启用 IAP。
向 IAP 服务代理授予调用方角色：
```
gcloud beta run services add-iam-policy-binding SERVICE_NAME \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com' \
    --role='roles/run.invoker'
```
替换以下内容：
- SERVICE_NAME：服务名称
- PROJECT_NUMBER：项目编号
1. 在新 Cloud Run 服务或现有 Cloud Run 服务上启用 IAP。
新建服务
如需部署新服务，请运行以下命令：
gcloud beta run deploy SERVICE_NAME \ --image=CONTAINER_IMAGE \ --region=REGION \ --project=PROJECT_ID \ --allow-unauthenticated \ --iap \ --functional-type=mcp-server
替换以下内容：
- SERVICE_NAME：服务名称
- CONTAINER_IMAGE：您的容器映像
- REGION：部署服务的区域
- PROJECT_ID：已启用 Cloud Run 的项目的 ID。
现有服务
如需更新现有实例，请运行以下命令：
gcloud run services update SERVICE_NAME \ --region=REGION \ --iap \ --functional-type=mcp-server
替换以下内容：
- SERVICE_NAME：服务名称。
- REGION：区域。
创建和配置 OAuth 客户端。

按照共享 OAuth 客户端以进行程序化访问中的说明注册 OAuth 客户端的通用客户端 ID，以便与 IAP 搭配使用。

请务必记录完成此步骤时获得的以下值：
- OAuth 客户端 ID
- OAuth 客户端密钥
- 重定向 URI
通过修改 Gemini 主目录 (~/.gemini/) 中的 settings.json 文件，将 Gemini CLI 等客户端或代理配置为连接到已部署的 MCP 服务器。

以下是 settings.json 模板：
```
{
  "mcpServers": {
    "my_mcp_server": {
      "httpUrl": "https://SERVICE_URL",
      "oauth": {
        "enabled": "true",
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET",
        "scopes": [ "email", "openid" ],
        "redirectUri": "REDIRECT_URI"
      }
    }
  }
}
```
替换以下内容：
- SERVICE_URL：Cloud Run 服务网址。
- OAUTH_CLIENT_ID：第 2 步中的客户端 ID。
- OAUTH_CLIENT_SECRET：第 2 步中的客户端密钥。
- REDIRECT_URI：重定向 URI，必须与第 2 步中的 URI 一致。
测试您是否可以连接到 MCP 服务器。

后续步骤

概览

Agent Gateway 概览

Agent Gateway 概览。

指南

配置内容和业务政策

了解如何配置内容政策和商家政策。

指南

测试政策

了解如何测试政策。

配置 IAM 代理政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

使用 IAP 创建 IAM 允许政策

创建代理到注册表的政策

控制台

gcloud

创建代理到代理的出站流量政策

控制台

gcloud

创建代理到 MCP 服务器的出站政策

控制台

gcloud

创建从代理到端点的出站流量政策

控制台

gcloud

使用 IAP 对 Cloud Run MCP 服务器进行身份验证

新建服务

现有服务

后续步骤

Agent Gateway 概览

配置内容和业务政策

测试政策

配置 IAM 代理政策