Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用 Service Extensions 委托授权

本页介绍了如何使用 Service Extensions 将 Agent Gateway 的授权委托给 Identity-Aware Proxy、Model Armor 和其他自定义授权引擎。

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

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

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

授权扩展程序

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

授权扩展程序可让您拦截并评估通过代理网关部署的请求。它会实时对您管理的外部服务进行 gRPC 调用，以便您在流量继续到达其目的地之前检查、修改甚至阻止流量。

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

准备工作

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

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

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

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

将授权委托给 IAP

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

以下步骤展示了如何为代理网关实例配置具有授权政策的授权扩展程序。

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

IAP 要求您的代理在绑定到网关的代理注册表资源中注册。
配置授权扩展程序以指向 IAP。
1. 在 YAML 文件中定义扩展程序。使用提供的示例值。
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF
```
  如果您想以试运行仅审核模式部署扩展程序，以便在不强制执行授权政策的情况下测试该政策，可以指定 DRY_RUN 字段。这样一来，您就可以验证政策，并最大限度地降低因配置错误而导致流量中断的风险：
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
EOF
```
  准备好开始强制执行政策后，请移除 DRY_RUN 元数据字段。
2. 导入授权扩展服务。使用 gcloud beta service-extensions authz-extensions import 命令，并提供以下示例值。
```
gcloud beta 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 beta 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 控制台为代理网关启用 Model Armor，请执行以下步骤：

创建所需的 Model Armor 模板。
如需在创建智能体网关时启用 Model Armor，请参阅配置智能体网关（通过使用启用 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 Runtime，则推理引擎服务代理还需要这些权限，如通过代理网关路由 Agent Runtime 流量中所述。

gcloud

创建所需的 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 beta service-extensions authz-extensions import 命令。

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

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

定义将扩展程序 my-ma-content-authz-ext 与代理网关相关联的授权政策。

代理到任意目的地

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 beta network-security authz-policies import 命令以及以下示例值。

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

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

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

使用 FQDN 目标时，扩展程序会使用 HTTP2 协议和 TLS 加密来与端口 443 上的端点通信。不过，该扩展程序不会验证服务器证书。因此，为了提高安全性，您必须确保解析的端点位于 VPC 网络内。另请确保在代理网关项目与您的 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 beta 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 授权扩展程序和指向该扩展程序的授权政策。

定义授权扩展服务。

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

创建授权扩展服务。

gcloud beta 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：代理网关的名称。

创建授权政策。

gcloud beta 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 beta 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 beta 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 授权政策。此政策应指向您的多功能授权扩展程序。与为 REQUEST_AUTHZ 和 CONTENT_AUTHZ 配置文件使用单独的扩展程序相比，此方法可通过单个扩展程序和 ext_proc 连接实现这两种类型的授权，从而缩短延迟时间。

基于 MCP 协议属性的授权

代理网关会解析请求中的 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 政策示例

此示例禁止所有提示/ 方法访问代理网关后面的 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 beta 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 个自定义授权政策。
如果您将自定义授权扩展程序与 CONTENT_AUTHZ 配置文件搭配使用，则这些扩展程序必须支持 ext_proc 协议和 FULL_DUPLEX_STREAMED 模式（用于正文事件）。
如果您配置了多个使用同一配置文件的自定义授权政策，则无法保证它们的执行顺序。

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

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

后续步骤

指南

Monitor Agent Gateway

了解如何监控代理网关。

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

授权扩展程序

准备工作

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

将授权委托给 IAP

向 Model Armor 委托授权

控制台

gcloud

代理到任意目的地

客户端到代理

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

将 IAP 授权与 Model Armor 保护措施相结合

基于 MCP 协议属性的授权

限制

后续步骤

Monitor Agent Gateway

使用 Service Extensions 委托授权