排查 IAM 统一访问权限政策方面的问题

本文档可帮助您诊断和解决为 Agent Gateway 出站流量配置和强制执行 IAM Unified Access Policies (UAP) 时的常见问题。

政策违规处置和访问失败

本部分介绍了与违规处置相关的问题。

政策未强制执行

症状：即使配置了 IAM 拒绝规则或限制性允许规则来阻止访问，代理仍可以访问目标工具、MCP 服务器或端点。

原因：Agent Gateway 授权扩展程序正在试运行模式下运行，或者政策绑定范围与目标资源不匹配。在试运行模式下，系统会评估访问决策并记录下来以供审核，但绝不会屏蔽请求。

解决方案：

  1. 将试运行模式切换为实施模式：首先，检查您的授权扩展配置文件 (iap-request-authz-extension.yaml)。如果 iamEnforcementMode 设置为 "DRY_RUN"，请将其更新为 "ENFORCE"（或移除 DRY_RUN 设置），然后使用 gcloud CLI 重新导入扩展：

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    替换以下内容：

    • EXTENSION_NAME：授权扩展程序的名称
    • EXTENSION_FILE：YAML 扩展程序配置的文件名
    • LOCATION：网关部署到的 Google Cloud 区域

  2. 验证网关授权政策委托：验证您的网关授权政策 (policyProfile: REQUEST_AUTHZ) 是否已绑定到正确的 Agent Gateway 实例 (target.resources)。

  3. 检查政策绑定范围：验证 IAM UAP 是否绑定到流量到达的目标资源范围。

  4. 检查规则优先级：在组合政策中，拒绝规则会明确覆盖同一范围内的允许规则。不过，请检查在注册表或项目级层绑定的具有更宽泛允许规则的 UAP 是否在没有条件限制的情况下授予访问权限。

强制执行的政策会阻止代理访问

症状：启用 Agent Gateway 政策强制执行后，智能体的出站流量请求失败，并显示 HTTP 403 Forbidden 或 PERMISSION_DENIED 错误。

原因：

  • UAP 中未指定代理的身份。

  • 未向该智能体的身份授予目标资源的 iap.resources.egressViaIAP 权限。

  • 确切的目标主机名未在代理注册表中注册

  • 请求属性不满足 UAP 中的通用表达式语言 (CEL) 条件。

解决方案：

  1. 切换到试运行模式，实现无中断调试：在诊断故障时，请暂时将授权扩展切换到试运行模式 (iamEnforcementMode: "DRY_RUN")，以便在您检查审核日志时，活跃的代理流量不会被屏蔽。

  2. 查询 Cloud Audit Logs：查询 Cloud Audit Logs 以检查确切的授权检查和 CEL 属性评估：

    gcloud

    运行以下 gcloud logging read 命令：

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    将 PROJECT_ID 替换为您的项目 ID。

    控制台

    1. 在 Google Cloud 控制台中，前往 Logs Explorer 页面。
    2. 选择您的项目。
    3. 在查询编辑器中，输入以下查询： 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. 点击运行查询。
    5. 展开日志条目并检查 protoPayload.authorizationInfo，查看哪个目标资源 URI 和权限未能通过评估。

  3. 验证主机名是否完全匹配：Agent Gateway 会完全匹配目标主机名。Google API 或第三方服务可能会通过多个主机名变体进行解析，具体取决于 SDK 版本、区域客户端配置或 mTLS 使用情况，例如 us-central1-aiplatform.googleapis.com、us-central1-aiplatform.mtls.googleapis.com 或 aiplatform.googleapis.com。

    • 如果您依赖于已注册的目标，请确保每个确切的主机名变体都在代理注册表中注册。
    • 如果代理访问未注册的端点，请验证未注册的端点政策是否为该主机和路径授予 iap.resources.egressViaIAP。

  4. 验证政策绑定在各个范围内的覆盖范围：检查三个受支持的范围之一是否存在政策绑定：

    • 注册表范围：授予对注册表中所有代理、MCP 服务器和端点的访问权限。
    • 按资源：授予对特定已注册 MCP 服务器、端点或代理的访问权限。
    • 未注册的端点：授予对 Agent Registry 之外的目标位置的访问权限。
    • 注意：在描述目标资源的政策绑定时，如果返回的输出包含 "etag" 字段但没有绑定，则该目标不存在 IAM 政策。

  5. 验证 CEL 条件属性值：将 Cloud Audit Logs 中记录的请求属性值与 UAP 条件表达式中的字面量值进行比较：

    • 区分大小写的字符串匹配：CEL 条件中的字符串比较区分大小写。验证复制或输入的值（例如 MCP 工具名称 [destination.agent_registry.mcp_server.tool.name]、MCP 服务器或代理资源名称 [destination.agent_registry.mcp_server.name、destination.agent_registry.agent.name] 或 HTTP 方法 [destination.unregistered.method]）是否与请求中的大小写和拼写完全一致。
    • 未注册目的地的各种主机和路径：如果出站流量目的地包含端口（例如，destination.unregistered.host 包含 example.com:443）、子网域或可变网址路径 (destination.unregistered.path)，则除非完整字符串匹配，否则完全相等检查 (==) 会失败。对于 destination.unregistered.host 和 destination.unregistered.path，您可以使用 .startsWith()、.endsWith() 或 .contains()，而不是完全相等 (==)：
      • 使用 .startsWith() 按前缀（例如 destination.unregistered.path.startsWith('/v2/process')）过滤网址路径。
      • 使用 .endsWith() 可授予或拒绝访问共享指定后缀（例如 destination.unregistered.host.endsWith('.example.com')）的所有子网域。

常见的界面、gcloud 和 REST API 出错提示

本部分介绍了出错提示以及如何解决这些错误。

找不到政策

错误消息：

  • 控制台界面：“请求的政策不存在。请验证所选资源是否存在该政策。
  • API/gcloud：POLICY_NOT_FOUND/HTTP 404 Not Found

原因：更新请求或政策绑定中指定的 UAP ID 在项目或位置中不存在，或已被删除。

解决方案：使用 gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global 列出项目中的所有可用 UAP，以在绑定或更新 UAP 之前确认确切的政策 ID 和位置。

超出目标绑定限制

错误消息：

  • 控制台界面：“所选目标已达到访问权限政策绑定数量上限。请先删除现有绑定，然后再添加新绑定。
  • API/gcloud：TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

原因：您尝试附加到目标资源（例如 MCP 服务器或注册表）的政策绑定数量超过了每个目标允许的上限。

解决方案：不要为每个单独的规则创建单独的 UAP 和绑定，而是将多个允许或拒绝规则整合到单个 UAP 中。使用 gcloud iam policy-bindings delete 移除未使用的绑定。

已超出政策绑定上限

错误消息：

  • 控制台界面：“所选政策已达到绑定数量上限。请先删除现有绑定，然后再添加新绑定。
  • API/gcloud：TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

原因：单个 UAP 附加到项目中过多不同的目标资源。

解决方案：在更广泛的范围（例如注册表范围 [AgentRegistry] 或项目范围）绑定政策，并使用 CEL 属性条件（例如 destination.agent_registry.mcp_server.name）来控制对政策规则中各个工具的访问。

超出条件限制

错误消息：

  • 控制台界面：“此政策已达到属性 条件数量上限。请移除一些条件，以便保存更改。”
  • API/gcloud：TOO_MANY_CONDITIONS/政策中的规则超出了条件限制。

原因：单个允许或拒绝规则包含的精细访问权限控制 (FGAC) 属性条件或复杂子表达式超出了单个规则支持的数量。

解决方案：使用 CEL 逻辑运算符（&&、||）或集合包含查找 (in) 来整合属性检查，或者将表达式拆分到同一 UAP 中的多个规则中。

规则详情已过时

错误消息：

  • 控制台界面：“规则详情已过时。自此页面加载完成后，此规则已被其他用户修改。请刷新页面以获取当前详情，然后再进行修改或删除。”
  • API/gcloud：由于 etag 不匹配，HTTP 412 Precondition Failed/ABORTED。

原因：在您检索 UAP 后，另一位管理员或自动化流程修改了 UAP，导致请求的 etag 与活跃服务器状态不同。

解决方案：刷新控制台页面，检索有效的政策详细信息和 etag，然后再保存修改。使用 REST API 时，请先执行 GET 请求以检索有效的 "etag" 值，并将其包含在 PATCH 请求载荷中。

无法删除政策中的最后一条规则

错误消息：

  • Console 界面：“无法删除此规则。“默认政策”必须包含至少一条规则。如需移除此规则，请改为删除政策。或“这是 <policy name> 中的最后一条规则。删除该规则也会删除政策并永久移除所有关联的绑定，这可能会影响代理对资源的访问权限。”

原因：IAM UAP 无法在没有规则的情况下保存。

解决方案：如果您想移除政策中的唯一规则，请删除整个政策。请注意，您必须先删除引用该政策的所有政策绑定，然后才能删除该政策本身。

自定义 CEL 表达式保留在“高级”标签页中

错误消息：

  • 控制台界面：“无法将自定义 CEL 表达式转换为标准界面选项。您的表达式会保留在“高级”标签页中。

原因：您在条件编辑器（“高级”标签页）中输入了复杂的 CEL 条件或函数，这些条件或函数无法映射到标准条件构建器的简化下拉选择器中。

解决方案：此消息是一条信息性通知。您的自定义 CEL 条件有效且已保留。继续直接在条件编辑器标签页中进行任何修改。

无法对目标属性调用函数

错误消息：

  • API/gcloud：Function '<var>FUNCTION_NAME</var>' cannot be called on the target '<var>ATTRIBUTE_NAME</var>' in namespace 'iap.googleapis.com'.（错误代码 3/INVALID_ARGUMENT）

原因：政策规则条件对不支持该函数的属性使用了 CEL 函数（例如 .startsWith()、.endsWith() 或 .contains()），或者尝试对布尔值属性或不受支持的字段调用字符串函数。在 UAP 中，字符串匹配函数仅在 destination.unregistered.host 和 destination.unregistered.path 上受支持。

解决方案：更新 CEL 条件表达式，使其仅使用目标属性支持的操作：

  • 未注册的主机和路径属性（destination.unregistered.host、destination.unregistered.path）：使用 ==、!=、in、.startsWith()、.endsWith() 或 .contains()。
  • 其他字符串属性（destination.unregistered.method 和 destination.agent_registry.* 字符串属性）：使用 ==、!= 或 in。
  • 布尔值属性（例如 destination.is_registered、工具注解）：使用逻辑比较（==、!=）。

如需查看属性和受支持操作的完整列表，请参阅适用于 UAP 的 CEL 属性。

政策中指定的用户不属于允许的客户

错误消息：

  • API/gcloud：One or more users named in the policy do not belong to a permitted customer.（错误代码 3/INVALID_ARGUMENT）

原因：IAM UAP 默认对添加到 ALLOW 规则的主账号强制执行内置且不可配置的网域限制共享 (DRS)。ALLOW 规则的 principals 数组中指定的一个或多个主体身份（例如 Agent Identity、Workload Identity、用户身份或服务账号）不属于创建或更新政策的项目所在的 Google Cloud组织。此内置检查不依赖于组织政策限制条件（例如 constraints/iam.allowedPolicyMemberDomains 或 constraints/iam.managed.allowedPolicyMembers），并且无法停用。

解决方案：检查政策配置文件（例如在 gcloud iam access-policies create 或 update 中使用 --details-rules 标志指定的 JSON 或 YAML 文件）的 ALLOW 规则中的 principals 数组。移除所有外部主账号，并确保所有指定的主账号身份都属于项目所在的 Google Cloud 组织。

后续步骤