使用 Service Extensions 委托授权

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

授权政策和扩展程序

借助授权政策，您可以对通过 Agent Gateway 发布的端点的流量强制执行集中式访问权限控制和治理政策。为了处理复杂的访问权限控制、内容安全和治理决策，Agent Gateway 可让您通过授权扩展程序配置授权政策，从而将授权和内容安全决策委托给您选择的指定授权引擎。

授权扩展程序会拦截通过 Agent Gateway 部署的请求，并向指定的授权服务发出实时 gRPC 调用。这样一来，服务便可在流量继续传输到目的地之前检查、修改或阻止流量。您可以将授权委托给 Cloud de Confiance Identity-Aware Proxy、Model Armor 和语义治理政策等服务，也可以委托给您选择的任何自定义授权引擎。

授权政策使用政策配置文件来确定发送给授权扩展程序的流量数据类型：

• 基于请求的授权 (REQUEST_AUTHZ)：在处理任何应用载荷之前评估 HTTP 请求标头。此配置文件用于身份验证和访问权限控制，例如将授权委托给 Identity-Aware Proxy。
• 基于内容的授权 (CONTENT_AUTHZ)：评估完整的 HTTP 请求和响应载荷。此配置文件用于深度内容检查和 AI 安全，例如委托给 Model Armor 以确保提示和回答安全，或委托给语义治理政策以强制执行自然语言限制。

自定义授权引擎可以使用 REQUEST_AUTHZ 或 CONTENT_AUTHZ 扩展程序，具体取决于它们是检查标头还是完整的应用载荷。

您可以为基于请求的政策和基于内容的政策分别配置授权扩展程序，也可以在网关上将两者结合起来，以实现全面的安全性。 如需查看推荐配置，请参阅推荐的入站和出站配置。

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

建议的入站流量和出站流量配置

为了在整个智能体生命周期内实现全面的安全性，我们建议采用以下多网关架构模式：

• 客户端到代理的网关：客户端到代理（入站）网关仅支持单个 CONTENT_AUTHZ 政策。这意味着，您无法在入站流量上同时使用 Model Armor 和语义治理政策。我们强烈建议使用 Model Armor CONTENT_AUTHZ 政策来防范提示注入攻击。不过，如果您想改用语义治理政策扩展程序，则必须确保网关上未配置 Model Armor。 Ingress 网关不支持其他类型的服务扩展。

• 智能体到任意位置的网关：智能体到任意位置（出站）网关最多支持 4 项授权政策。出站网关支持 REQUEST_AUTHZ 和 CONTENT_AUTHZ 政策配置文件，您可以在此限制范围内配置每种类型的多个政策。

  我们建议采用以下配置：

  • 一种 REQUEST_AUTHZ 政策，用于委托 Identity-Aware Proxy (IAP) 授权代理身份。
  • 一项或多项 CONTENT_AUTHZ 政策，用于将进一步的决策委托给 Model Armor 或 semantic governance policy，以防范敏感数据暴露，并对传出的工具调用和响应强制执行自然语言限制。

  如需详细了解政策的评估方式，请参阅出站流量政策评估。

这种多网关拓扑可确保 Model Armor 筛查传入的提示，而 IAP、Model Armor 和语义治理政策则筛查传出的回答。

出站流量政策评估

如果出站网关上配置了多个授权政策，系统会根据其政策配置文件类型按顺序评估这些政策：

1. REQUEST_AUTHZ基于标头的政策：系统会先评估这些政策类型。例如，IAP 扩展程序会检查调用代理的 mTLS 身份并验证其 IAM 允许政策，然后再处理任何内容。如果请求未通过此检查，则会被立即拒绝。
2. CONTENT_AUTHZ（基于内容的）政策：接下来会评估这些政策类型。如果请求通过了基于标头的检查，系统会将载荷流式传输到基于内容的授权扩展程序（例如语义治理政策引擎），以进行深入的内容检查和合规性评估。

准备工作

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

• Agent Gateway 已部署。请参阅配置 Agent Gateway。

• 您必须拥有已部署的 Agent Gateway 资源的 networkservices.agentGateways.use IAM 权限，才能将授权政策附加到网关。

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

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

将授权委托给 IAP

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

以下步骤展示了如何为 Agent Gateway 实例配置具有授权政策的授权扩展。

1. 准备工作：关闭禁止将绑定访问权限的政策绑定到资源 (constraints/iam.managed.disableAccessPolicyBindings) 受管理的组织政策限制条件的强制执行。默认情况下，此布尔值限制条件会针对新组织启用，并会阻止您将 IAM 统一访问政策绑定到资源。如需了解详情，请参阅使用布尔值规则更新政策。

2. 为代理和工具创建所需的 IAM 出站流量政策。如需了解详情，请参阅创建 IAM 代理政策。

3. 如需在创建智能体网关时启用 IAP（通过使用访问权限授权参数），请参阅以“智能体到任意位置（出站）”模式配置智能体网关。

4. 配置授权扩展程序以指向 IAP。

   1. 在 YAML 文件中定义扩展程序。使用提供的示例值。如果您想以试运行仅审核模式部署扩展程序，以测试授权政策而不强制执行该政策，可以在 metadata 块内指定 iamEnforcementMode 字段。

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      

      如果您想以试运行仅审核模式部署扩展程序，以便在不强制执行授权政策的情况下测试该政策，可以在 metadata 块内指定 iamEnforcementMode 字段。这样一来，您就可以验证政策，并最大限度地降低因配置错误而导致流量中断的风险：

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
        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
      

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

   1. 定义将 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。

   2. 将授权政策导入项目。将 gcloud network-security authz-policies import 命令与以下示例值搭配使用。

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

向 Model Armor 委托授权

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

以下示例展示了如何使用 Agent Gateway 的授权政策配置此类授权扩展。

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

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

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

1. 如需为特定 FQDN（例如 mycustomauthz.internal.net）配置具有授权政策的授权扩展程序，请在扩展程序 YAML 文件中将该 FQDN 指定为 service 的值，如以下示例所示。此示例假设您已在 VPC 网络中部署一个服务器，该服务器以 FULL_DUPLEX_STREAMED 正文处理模式实现 ext_proc 协议。

   cat >custom-authz-extension.yaml <<EOF
   name: my-custom-authz-ext
   service: mycustomauthz.internal.net
   failOpen: false
   timeout: 1s
   EOF
   

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

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

3. 创建扩展程序后，配置 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
   

4. 创建授权政策。

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

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

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

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

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

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

   1. 定义授权扩展程序。metadata 下的 iapPolicyVersion 字段是必需字段。

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

   2. 创建授权扩展程序。

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

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

   3. 配置委托给扩展程序的 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 的名称。

   4. 创建授权政策。

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

2. 配置 CONTENT_AUTHZ 授权扩展程序（委托给 Model Armor）和指向该扩展程序的授权政策。

   1. 定义扩展。

      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: false
      timeout: 1s
      EOF
      

      替换以下内容：

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

   2. 创建授权扩展程序。

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

   3. 配置委托给扩展程序的 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
      

   4. 创建授权政策。

      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。

1. 配置授权政策。

   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
   

2. 创建授权政策。

   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：资源的位置。

限制

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

• 每个网关的授权政策数量上限取决于网关模式：

  • 对于代理到任意位置（出站）网关，无论政策配置文件（REQUEST_AUTHZ 或 CONTENT_AUTHZ）如何，每个网关最多可以配置四项授权政策。
  • 对于客户端到代理 (ingress) 网关，您最多可以配置一个 CONTENT_AUTHZ 政策。

  如需了解详情，请参阅建议的入站流量和出站流量配置。

• 如果您将自定义授权扩展程序与 CONTENT_AUTHZ 配置文件搭配使用，则这些扩展程序必须支持 ext_proc 协议和 FULL_DUPLEX_STREAMED 模式（针对身体事件）。

• 如果您配置了多个使用同一配置文件的自定义授权政策，则无法保证它们的执行顺序。

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

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

• 如需了解适用于标注的限制，请参阅标注的限制。

后续步骤