本页介绍了如何使用服务扩展程序将 Agent Gateway 的授权委托给 Identity-Aware Proxy、Model Armor 和其他自定义授权引擎。
借助授权政策，您可以对通过代理网关发布的端点的流量强制执行集中式访问权限控制和治理政策。借助这些政策，您可以根据 mTLS 身份、请求和响应属性来控制访问权限，从而管理流量，甚至可以根据所用的协议特定属性（例如 MCP 服务器）进行自定义。
授权政策使用政策配置文件来确定要执行的授权类型。您可以使用基于请求的授权政策 (REQUEST_AUTHZ)，该政策依赖于 HTTP 请求标头中的信息来允许或拒绝流量。或者，如果您需要对应用载荷进行更深入的检查，以允许或拒绝流量，可以使用基于内容的授权政策 (CONTENT_AUTHZ)。
如需详细了解授权政策、政策配置文件及其使用情形，请参阅授权政策概览。
授权扩展程序
有时，复杂的授权决策无法使用授权政策轻松表达。借助 Agent Gateway，您可以配置包含授权扩展程序的授权政策，以将授权决策委托给自定义授权引擎。
借助授权扩展程序，您可以拦截并评估通过 Agent Gateway 部署的请求。它会向您管理的外部服务发出实时 gRPC 调用，以便您在流量继续流向其目的地之前检查、修改甚至阻止流量。
扩展程序会根据配置的授权政策检查数据。您可以分别为基于请求的授权政策和基于内容的授权政策单独配置授权扩展程序，也可以同时使用这两种授权扩展程序来实现全面的安全性。
准备工作
在开始之前，请确保满足以下要求：
代理网关已部署。请参阅配置 Agent Gateway。
您必须对已部署的 Agent Gateway 资源拥有
agentGateway.useIAM 权限，才能将授权政策附加到网关。
使用扩展程序配置授权政策
本部分介绍如何配置授权政策，以将授权和内容安全决策委托给 Identity-Aware Proxy、Model Armor 和其他自定义服务。
将授权委托给 IAP
您可以配置请求授权扩展程序，以将授权政策的访问权限决策委托给 IAP。
以下步骤展示了如何为代理网关实例配置具有授权政策的授权扩展程序。
为代理和工具创建所需的 IAM 出站政策。如需了解详情，请参阅创建 IAM 代理政策。
如需在创建智能体网关时启用 IAP（通过使用访问权限授权参数），请参阅以“智能体到任意位置（出站）”模式配置智能体网关。
IAP 要求代理向绑定到网关的代理注册表资源注册。
配置授权扩展程序以指向 IAP。
在 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"字段。导入授权扩展服务。使用
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。
以下示例展示了如何为代理网关配置具有授权政策的此类授权扩展服务。
控制台
如需使用 Google Cloud 控制台为 Agent Gateway 启用 Model Armor，请执行以下步骤：
创建所需的 Model Armor 模板。
如需在创建 Agent Gateway 时启用 Model Armor（通过选中启用 Model Armor 复选框），请参阅配置 Agent Gateway。Model Armor 模板在“客户端到代理”模式和“代理到任意位置”模式下均受支持。
使用 Model Armor 时，您必须向代理网关服务账号授予使用 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 Gateway 用于 Agent Runtime，则推理引擎服务代理还需要这些权限，如通过 Agent Gateway 路由 Agent Runtime 数据流量中所述。
- 在包含网关的项目中创建
gcloud
创建所需的 Model Armor 模板。
使用 Model Armor 时，您必须向代理网关服务账号授予使用 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" EOFpolicyProfile的值设置为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 目标时，扩展程序会使用 HTTP2 协议和 TLS 加密来与端口 443 上的端点通信。不过，该扩展程序不会验证服务器证书。因此，为了提高安全性，您必须确保解析的端点位于 VPC 网络内。另请确保在 Agent Gateway 项目与您的 VPC 网络之间设置了 DNS 对等互连。
如需为特定 FQDN（例如
mycustomauthz.internal.net）配置具有授权政策的授权扩展程序，请在扩展程序 YAML 文件中将该 FQDN 指定为service的值，如以下示例所示。此示例假定您已在 VPC 网络中部署了一个实现ext_authz协议的服务器。cat >custom-authz-extension.yaml <<EOF name: my-custom-authz-ext service: mycustomauthz.internal.net failOpen: true timeout: 1s wireFormat: EXT_AUTHZ_GRPC 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: REQUEST_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
请注意，当授权扩展程序与使用 REQUEST_AUTHZ 配置文件的授权政策相关联时（如本示例所示），网关仅在请求标头到达时调用该扩展程序。授权扩展程序无法看到请求正文、响应标头和响应正文。
将 IAP 授权与 Model Armor 保护措施相结合
为了实现全面的安全性，我们建议您设置一个具有 REQUEST_AUTHZ 政策配置文件的自定义授权政策，以及另一个具有 CONTENT_AUTHZ 政策配置文件的自定义授权政策。
以下示例使用 IAP 作为集中式请求授权系统，并使用 Model Armor 作为 AI 护栏。如前面的示例所示，您可以将这些内容替换为服务扩展程序，以使用自己的自定义解决方案。
配置委托给 IAP 的
REQUEST_AUTHZ授权扩展程序和指向该扩展程序的授权政策。定义授权扩展程序。
metadata下的iapPolicyVersion字段为必填字段，必须设置为"V1"。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 连接实现这两种类型的授权，与为 REQUEST_AUTHZ 和 CONTENT_AUTHZ 配置文件使用单独的扩展程序相比，可以缩短延迟时间。
基于 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 EOFDENY政策示例此示例禁止所有提示/ 方法访问代理网关后面的 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：资源的位置。
限制
使用授权政策时，存在以下限制：
- 对于“代理到任意位置”（出站）网关，无论政策配置文件如何，您最多可以为每个网关配置四项自定义授权政策。
- 对于客户端到代理 (ingress) 网关，您最多可以配置一个
CONTENT_AUTHZ政策。我们强烈建议使用 Model Armor 来防范提示注入攻击。不过，如果您想改用语义治理政策扩展程序，则必须确保网关上未配置 Model Armor。Ingress 不支持其他类型的服务扩展。 - 如果您将自定义授权扩展程序与
CONTENT_AUTHZ配置文件搭配使用，则这些扩展程序必须支持ext_proc协议和FULL_DUPLEX_STREAMED模式（用于正文事件）。 - 如果您配置了多个使用同一配置文件的自定义授权政策，则无法保证它们的执行顺序。
此外，如需详细了解授权扩展程序的限制，请参阅以下部分：
后续步骤
Codelab：使用 Agent Platform 管理代理工作负载
了解如何使用 Gemini Enterprise Agent Platform 上的 Agent Gateway 来监管智能体工作负载。