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

使用 Service Extensions 委托授权

在本页中，您可以了解如何使用 Service Extensions 将 Agent Gateway 的授权委托给 Identity-Aware Proxy、Model Armor 和其他自定义授权引擎。

借助授权政策，您可以对通过 Agent Gateway 发布端点的流量强制执行集中式访问权限控制和治理政策。借助这些政策，您可以根据 mTLS 身份、请求和响应属性来控制访问权限，从而管理流量，甚至可以根据所使用的协议专用属性（例如 MCP 服务器）进行自定义。

授权政策使用政策配置文件来确定要执行的授权类型。您可以使用基于请求的授权政策 (REQUEST_AUTHZ)，该政策依赖于 HTTP 请求标头中的信息来允许或拒绝流量。或者，当您需要对应用载荷执行更深入的检查以允许或拒绝流量时，可以使用基于内容的授权政策 (CONTENT_AUTHZ)。

如需详细了解授权政策、政策配置文件及其用例，请参阅授权政策概览。

授权扩展程序

有时，复杂的授权决策无法使用授权政策轻松表达。借助 Agent Gateway，您可以使用授权扩展程序配置授权政策，以将授权决策委托给自定义授权引擎。

借助授权扩展程序，您可以拦截并评估通过 Agent Gateway 部署的请求。它会向您管理的外部服务发出实时 gRPC 调用，以便您可以在流量继续流向其目的地之前检查、修改甚至阻止流量。

扩展程序会根据配置的授权政策检查数据。您可以分别为基于请求的授权政策和基于内容的授权政策配置授权扩展程序，也可以同时使用两者以实现全面的安全性。

准备工作

在开始之前，请确保满足以下要求：

已部署 Agent Gateway。请参阅配置 Agent Gateway。
您必须对已部署的 Agent Gateway 资源拥有 agentGateway.use IAM 权限，才能将授权政策附加到网关。

使用扩展程序配置授权政策

本部分介绍如何配置授权政策，以将授权和内容安全决策委托给 Identity-Aware Proxy、Model Armor 和其他自定义服务。

将授权委托给 IAP

您可以配置请求授权扩展程序，以将授权政策的访问权限决策委托给 IAP。

以下步骤介绍了如何为 Agent Gateway 实例配置包含授权政策的授权扩展程序。

为您的代理和工具创建所需的 IAM 出站政策。如需了解详情，请参阅创建 IAM 代理政策。
如需在创建 Agent Gateway 时启用 IAP （使用访问权限授权 参数），请参阅以“代理到任意目的地（出站流量）” 模式配置 Agent Gateway。

IAP 要求您的代理在绑定到网关的 Agent Registry 资源中注册。
配置授权扩展程序以指向 IAP。
1. 在 YAML 文件中定义扩展程序。使用提供的示例值。如果您想以试运行的仅审核模式部署扩展程序，以测试授权政策而不强制执行该政策，则可以在 metadata 块内指定 iamEnforcementMode 字段。
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF
```
  如果您想以试运行的仅审核模式部署扩展程序，以测试授权政策而不强制执行该政策，则可以在 metadata 块内指定 iamEnforcementMode 字段。这样，您就可以验证政策并最大限度地降低因配置错误而导致流量中断的风险：
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
  iamEnforcementMode: "DRY_RUN"
EOF
```
  准备好开始强制执行政策后，请从 metadata 块中移除 iamEnforcementMode: "DRY_RUN" 字段。
2. 导入授权扩展程序。使用 gcloud service-extensions authz-extensions import 命令以及以下示例值。
```
gcloud service-extensions authz-extensions import my-iap-request-authz-ext \
    --source=iap-request-authz-extension.yaml \
    --location=LOCATION
```

在同一项目中，配置将决策委托给扩展程序的授权政策。

定义将 my-iap-request-authz-ext 扩展程序与网关关联的授权政策。使用提供的示例值。

cat >iap-request-authz-policy.yaml <<EOF
name: my-iap-request-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-iap-request-authz-ext"
EOF

将 PROJECT_ID 替换为您的项目 ID。

将授权政策导入到项目中。使用 gcloud network-security authz-policies import 命令以及以下示例值。

gcloud beta network-security authz-policies import my-iap-request-authz-policy \
    --source=iap-request-authz-policy.yaml \
    --location=LOCATION

将授权委托给 Model Armor

您可以配置授权扩展程序，以将授权政策的内容安全决策委托给 Model Armor。

以下示例展示了如何为 Agent Gateway 配置包含授权政策的此类授权扩展程序。

控制台

如需使用 Google Cloud 控制台为 Agent Gateway 启用 Model Armor，请执行以下步骤：

创建所需的 Model Armor 模板。
如需在创建 Agent Gateway 时启用 Model Armor （使用启用 Model Armor 复选框），请参阅配置 Agent Gateway。Model Armor 模板在“客户端到代理”模式和“代理到任意目的地”模式下均受支持。
使用 Model Armor 时，您必须向 Agent Gateway 服务帐号授予使用 Model Armor 模板所需的权限。服务帐号的格式为 service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com，其中 PROJECT_NUMBER 是您在其中创建网关的项目的项目号。

即使网关和模板位于同一项目中，您也必须完成此步骤。授予以下角色：
- 在包含网关的项目中创建 roles/modelarmor.calloutUser 和 roles/serviceusage.serviceUsageConsumer 角色。
- 在包含 Model Armor 模板的项目中创建 roles/modelarmor.user 角色。
您需要使用 gcloud CLI 完成此步骤。
```
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
```
替换以下内容：
- GATEWAY_PROJECT_ID：您在其中创建网关的项目的项目 ID。
- GATEWAY_PROJECT_NUMBER：您在其中创建网关的项目的项目号。
- MODEL_ARMOR_PROJECT_ID：包含 Model Armor 模板的项目的项目 ID。
如果您将网关用于 Agent Runtime，则推理引擎服务代理也需要这些权限，如在通过 Agent Runtime 流量通过 Agent Gateway 路由中所述。

gcloud

创建所需的 Model Armor 模板。
使用 Model Armor 时，您必须向 Agent Gateway 服务帐号授予使用 Model Armor 模板所需的权限。服务帐号的格式为 service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com，其中 PROJECT_NUMBER 是您在其中创建网关的项目的项目号。

即使网关和模板位于同一项目中，您也必须完成此步骤。授予以下角色：
- 在包含网关的项目中创建 roles/modelarmor.calloutUser 和 roles/serviceusage.serviceUsageConsumer 角色。
- 在包含 Model Armor 模板的项目中创建 roles/modelarmor.user 角色。
```
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
```
替换以下内容：
- GATEWAY_PROJECT_ID：您在其中创建网关的项目的项目 ID。
- GATEWAY_PROJECT_NUMBER：您在其中创建网关的项目的项目号。
- MODEL_ARMOR_PROJECT_ID：包含 Model Armor 模板的项目的项目 ID。

配置授权扩展程序以指向 Model Armor。

在 YAML 文件中定义扩展程序。使用提供的示例值。

cat >ma-content-authz-extension.yaml <<EOF
name: my-ma-content-authz-ext
service: modelarmor.LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
    "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
    "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
    }
  ]'
failOpen: true
timeout: 1s
EOF

导入授权扩展程序。使用 gcloud service-extensions authz-extensions import 命令以及以下示例值。

gcloud service-extensions authz-extensions import my-ma-content-authz-ext \
   --source=ma-content-authz-extension.yaml \
   --location=LOCATION

使用扩展程序配置授权政策。

定义将扩展程序 my-ma-content-authz-ext 与 Agent Gateway 关联的授权政策。

代理到任意目的地

cat >ma-content-authz-policy.yaml <<EOF
name: my-ma-content-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/gateways/AGENT_GATEWAY_NAME"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext"
httpRules:
  - to:
      operations: [ { "paths": [ { "prefix": "/" } ] } ]
    when: >
      request.headers['content-type'] == 'application/json' ||
      request.headers['content-type'].startsWith('text/')
EOF

请注意以下几点：

policyProfile 的值设置为 CONTENT_AUTHZ。这表示自定义政策提供方会处理请求和响应流量，包括请求正文。
httpRules 参数演示了如何使用 CEL 属性创建与您要转发到 Model Armor 以进行评估的特定流量匹配的条件。在此示例中，规则与具有 application/json 或 text/ 内容类型的所有流量匹配。我们建议使用此类规则将 Model Armor 评估限制为相关流量。这样，您就可以将受支持的 LLM API、MCP 和 A2A 流量路由到 Model Armor，同时排除内部流量（例如代理 gRPC 调用）。

客户端到代理

cat >ma-content-authz-policy.yaml <<EOF
name: my-ma-content-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/gateways/AGENT_GATEWAY_NAME"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext"
EOF

policyProfile 的值设置为 CONTENT_AUTHZ。这表示自定义政策提供方会处理请求和响应流量，包括请求正文。

将授权政策导入到项目中。使用 gcloud network-security authz-policies import 命令以及以下示例值。

gcloud network-security authz-policies import my-ma-content-authz-policy \
  --source=ma-content-authz-policy.yaml \
  --location=LOCATION

将授权委托给自定义授权扩展程序

您可以配置自定义授权扩展程序，以将决策委托给自定义服务。这些自定义扩展程序只能以完全限定域名 (FQDN) 为目标。

使用 FQDN 目标时，扩展程序会使用带有 TLS 加密的 HTTP2 协议与端口 443 上的端点进行通信。不过，扩展程序不会验证服务器证书。因此，为了提高安全性，您必须确保解析的端点位于 VPC 网络内。此外，还要确保在 Agent Gateway 项目和 VPC 网络之间设置了 DNS 对等互连。

如需为特定 FQDN（例如 mycustomauthz.internal.net）配置包含授权政策的授权扩展程序，请将其指定为扩展程序 YAML 文件中 service 的值，如以下示例所示。此示例假定您已在 VPC 网络中部署服务器，该服务器以 FULL_DUPLEX_STREAMED 正文处理模式实现 ext_proc 协议。
```
cat >custom-authz-extension.yaml <<EOF
name: my-custom-authz-ext
service: mycustomauthz.internal.net
failOpen: true
timeout: 1s
EOF
```

创建授权扩展程序以指向自定义服务。

gcloud beta service-extensions authz-extensions import custom-authz-extension \
  --source=custom-authz-extension.yaml \
  --location=LOCATION

创建扩展程序后，配置将决策委托给授权扩展程序的 CUSTOM 授权政策。

  cat >authz-policy.yaml <<EOF
  name: authz-with-extension
  target:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
  policyProfile: CONTENT_AUTHZ
  action: CUSTOM
  customProvider:
    authzExtension:
      resources:
        - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension"
  EOF

创建授权政策。

gcloud network-security authz-policies import authz-policy-with-extension \
--source=authz-policy.yaml \
--location=LOCATION

请注意，当授权扩展程序与使用 CONTENT_AUTHZ 配置文件的授权政策关联时（如本示例所示），网关会为请求和响应载荷（标头和正文）调用该扩展程序，从而允许对代理流量进行深度内容检查、提示护栏和数据清理。默认情况下，CONTENT_AUTHZ 政策使用 FULL_DUPLEX_STREAMED 模式下的 Envoy ext_proc 协议来处理正文事件。

将 IAP 授权与 Model Armor 护栏相结合

为了实现全面的安全性，我们建议您设置一个包含 REQUEST_AUTHZ 政策配置文件的 CUSTOM 授权政策，以及另一个包含 CONTENT_AUTHZ 政策配置文件的 CUSTOM 授权政策。

以下示例使用 IAP 作为集中式请求授权系统，并使用 Model Armor 作为 AI 护栏。如之前的示例所示，您可以将这些系统/护栏中的每一个都替换为服务扩展程序，以使用您自己的自定义解决方案。

配置委托给 IAP 的 REQUEST_AUTHZ 授权扩展程序，以及指向该扩展程序的授权政策。

定义授权扩展程序。下的 iapPolicyVersion 字段是必需的，必须设置为 "V1"。metadata

cat >iap-extension.yaml <<EOF
name: iap-extension
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

创建授权扩展程序。

gcloud service-extensions authz-extensions import iap-extension \
--source=iap-extension.yaml \
--location=LOCATION

将 LOCATION 替换为扩展程序的区域。

配置委托给扩展程序的 REQUEST_AUTHZ 授权政策。

cat >authz-policy-request-authz.yaml <<EOF
name: authz-iap
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/iap-extension"
EOF

替换以下内容：

PROJECT_ID：您的项目 ID。
LOCATION：资源的位置。
AGENT_GATEWAY_NAME：Agent Gateway 的名称。

创建授权政策。

gcloud network-security authz-policies import authz-iap \
--source=authz-policy-request-authz.yaml \
--location=LOCATION

配置委托给 Model Armor 的 CONTENT_AUTHZ 授权扩展程序，以及指向该扩展程序的授权政策。

定义扩展程序。

cat >ma-extension-file.yaml <<EOF
name: ma-extension
service: modelarmor.LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
    "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID",
    "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID"
    }
  ]'
failOpen: true
timeout: 1s
EOF

替换以下内容：

LOCATION：Model Armor 模板所在的区域。
MODEL_ARMOR_PROJECT_ID：包含 Model Armor 模板的项目 ID。
RESPONSE_TEMPLATE_ID：响应模板的 ID。
REQUEST_TEMPLATE_ID：请求模板的 ID。

创建授权扩展程序。

gcloud service-extensions authz-extensions import ma-extension \
--source=ma-extension-file.yaml \
--location=LOCATION

配置委托给扩展程序的 CONTENT_AUTHZ 授权政策。

cat >authz-policy-content-authz.yaml <<EOF
name: authz-ma
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/ma-extension"
EOF

创建授权政策。

gcloud network-security authz-policies import ma-authz-policy \
--source=authz-policy-content-authz.yaml \
--location=LOCATION

当授权扩展程序与 CONTENT_AUTHZ 配置文件关联时，它会接收所有 ext_proc 事件，包括请求和响应标头、正文和尾部。如果基于 ext_proc 的授权扩展程序能够处理请求时授权和基于内容的授权，我们建议您配置包含 CONTENT_AUTHZ 政策配置文件的单个 CUSTOM 授权政策。此政策应指向您的多功能授权扩展程序。这种方法可以通过单个扩展程序和 ext_proc 连接启用这两种类型的授权，从而改善延迟时间配置文件。

将授权委托给语义治理政策

您可以配置授权扩展程序，以将授权政策的意图限制和自然语言限制决策委托给语义治理政策引擎 (semanticGovernancePolicyEngine)。

如需了解如何预配政策引擎并在网关上创建所需的 CONTENT_AUTHZ 授权政策和授权扩展程序绑定，请参阅将政策引擎连接到 Agent Gateway。

基于 MCP 协议属性的授权

Agent Gateway 会解析请求中的 MCP 协议载荷，并使提取的属性可用于授权政策。

您可以根据 MCP 方法参数（例如特定工具的名称）来限制访问权限。本部分向您展示了两个示例，一个用于 ALLOW 政策，另一个用于 DENY。

配置授权政策。

ALLOW 政策示例

此示例允许访问 MCP 服务器上的一组特定工具和基本协议功能，但不允许访问提示和资源。

编写 ALLOW 政策时，请确保指定 baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS，以便非访问权限特定的 MCP RPC（例如初始化、日志记录、完成、通知和 ping）继续正常运行。否则会导致无法建立 MCP 会话。

cat >authz-policy-restrict-tools.yaml <<EOF
name: my-authz-policy-restrict-tools
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
httpRules:
- to:
    operations:
    - mcp:
        baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS
        methods:
        - name: "tools/list"
        - name: "tools/call"
          params:
          - exact: "get_weather"
          - exact: "get_location"
action: ALLOW
EOF

DENY 政策示例

此示例禁止所有提示/ 方法访问 Agent Gateway 后面的 MCP 服务器。

cat >authz-policy-disallow-prompts.yaml <<EOF
name: my-authz-policy-disallow-prompts
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
httpRules:
- to:
    operations:
    - mcp:
        methods:
        - name: "prompts"
action: DENY
EOF

创建授权政策。
```
gcloud network-security authz-policies import AUTHZ_POLICY_NAME \
--source=AUTH_POLICY_YAML_FILE_PATH \
--location=LOCATION
```
替换以下内容：
- AUTHZ_POLICY_NAME：授权政策的名称。
- AUTH_POLICY_YAML_FILE_PATH：授权政策 YAML 文件的路径。
- LOCATION：资源的位置。

限制

使用授权政策时，存在以下限制：

对于“代理到任意目的地（出站流量）”网关，无论政策配置文件如何，您最多可以为每个网关配置 4 个自定义授权政策。
对于“客户端到代理（入站流量）”网关，您最多可以配置 1 个 CONTENT_AUTHZ 政策。我们强烈建议使用 Model Armor 来防范提示注入攻击。不过，如果您想改用语义治理政策扩展程序，则必须确保未在网关上配置 Model Armor。其他类型的服务扩展程序不支持入站流量。
如果您将自定义授权扩展程序与 CONTENT_AUTHZ 配置文件搭配使用，则这些扩展程序必须支持 ext_proc 协议和 FULL_DUPLEX_STREAMED 模式来处理正文事件。
如果您配置了多个使用相同配置文件的自定义授权政策，则无法保证其执行顺序。

此外，如需详细了解授权扩展程序的限制，请参阅以下部分：

如需了解适用于所有扩展程序的限制，请参阅扩展程序的限制。
如需了解适用于调用的限制，请参阅调用的限制。

后续步骤

Codelab

使用 Service Extensions 委托授权

授权扩展程序

准备工作

使用扩展程序配置授权政策

将授权委托给 IAP

将授权委托给 Model Armor

控制台

gcloud

代理到任意目的地

客户端到代理

将授权委托给自定义授权扩展程序

将 IAP 授权与 Model Armor 护栏相结合

将授权委托给语义治理政策

基于 MCP 协议属性的授权

限制

后续步骤

Codelab：使用 Agent Platform 治理智能体工作负载

监控 Agent Gateway

排查 Agent Gateway 问题

使用 Service Extensions 委托授权 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

授权扩展程序

准备工作

使用扩展程序配置授权政策

将授权委托给 IAP

将授权委托给 Model Armor

控制台

gcloud

代理到任意目的地

客户端到代理

将授权委托给自定义授权扩展程序

将 IAP 授权与 Model Armor 护栏相结合

将授权委托给语义治理政策

基于 MCP 协议属性的授权

限制

后续步骤

Codelab：使用 Agent Platform 治理智能体工作负载

监控 Agent Gateway

排查 Agent Gateway 问题

使用 Service Extensions 委托授权