策略集管理

权限要求

执行以下操作前，建议为您使用的 RAM 用户或角色分配 AliyunAgentIdentityFullAccess （管理策略集）以及AliyunAPIGFullAccess（绑定、解绑、查询AI网关）系统策略。

创建策略集

创建一个新的策略集，以便后续向其中添加具体策略。

1. 登录 AgentIdentity 控制台。

2. 在左侧导航栏，选择权限 > 策略集。

3. 单击创建策略集。

4. 在创建策略集页面，输入策略集名称和描述（可选），然后单击创建策略集按钮。

   说明

   • 策略集名称创建后不可修改。

   • 可创建的策略集数量存在限制，具体请参见使用限制。

向策略集中添加策略

创建策略集后，需要向其中添加具体的策略规则来定义访问控制逻辑。

1. 在策略集列表中，找到目标策略集，单击其名称。

2. 在策略集详情页，单击策略内容页签下的编辑策略内容。

3. 如当前策略集下没有策略，编辑器将自动新增一个策略并预填充策略名称。否则，单击新增策略按钮来添加。在策略编辑页面完成以下配置：

   • 策略名称：默认填充格式为Policy_{xxxxx}。

   • 描述（可选）：策略描述。

   • 策略语句：

     配置项	选项	说明
     效果	允许 / 拒绝	策略的授权效果，决定是允许还是拒绝匹配的请求。 一个策略集中至少需要有一条效果为允许的策略，否则该策略将拒绝所有请求。
     主体	全部主体 指定主体 工作负载身份 OAuth用户 自定义用户	策略适用的主体对象，由主体类型和主体ID组成。 指定主体类型时，如省略主体ID，将应用于该类型的全部主体对象；如指定主体ID，则主体范围将限定于匹配主体ID的对象。 一条策略中仅能指定一种主体类型，或该主体类型下的单个主体对象（指定主体ID时）。 当选择指定主体为OAuth用户时，可以进一步指定： 用户池：选择目标用户池，将策略范围限定为该用户池中的用户。 指定方式：选择如何进一步缩小主体范围： 主体 ID 或名称：输入用户的 ID 或名称，将策略精确匹配到指定用户。 所属角色：选择用户池中的角色，策略将应用于拥有该角色的所有用户，实现基于角色的访问控制（RBAC）。
     资源	指定网关资源	策略控制的目标AI网关资源。 指定并绑定网关后，所有经过该网关的请求均会被拦截进行授权评估。
     操作	全部操作 指定操作	策略允许或拒绝的具体MCP服务工具，由网关、服务、工具三个层级构成，以.分隔。如mcp-servers.order-service.create-order。支持： 同时指定多个操作，如： mcp-servers.order-service.create-order mcp-servers.order-service.get-order 仅指定网关或服务层级，代表允许或拒绝当前层级下的所有工具，如： 允许网关下的所有MCP服务工具：mcp-servers 允许指定MCP服务下的所有工具：mcp-servers.order-service
     条件	指定条件（可选）	策略生效的附加条件，以键值对的方式进行设置。 单条策略支持配置多个条件，各条件之间为逻辑“与”（AND）关系。

     如需使用反向排除条件（unless），请切换到脚本编辑器进行配置。关于 unless 的详细用法，请参见策略说明。

4. 单击提交，完成策略创建。

为策略集绑定AI网关

只有将策略集与 AI 网关绑定后，策略集中的策略才会应用于该网关的实际业务流量。

1. 在策略集列表中，找到目标策略集，单击其名称。

2. 在策略集详情页，切换到关联网关页签。单击绑定网关按钮。

3. 在绑定网关面板中，完成以下配置：

   • 选择网关：从网关列表中选择需要应用此策略集的 AI 网关。该网关需要与您在策略资源配置项中指定的网关一致。

   • 执行模式：选择策略集在网关上的工作方式。

     • 观察模式：仅记录策略评估结果，不会拦截任何请求。此模式主要用于测试和验证策略评估结果是否符合预期。建议在应用策略集至生产环境时先设置为观察模式，确保策略变更不会影响正常业务。

     • 拦截模式：严格执行策略评估结果。被拒绝的请求将被网关拦截，调用方收到错误响应（状态码403）。

4. 单击绑定网关。绑定任务将自动创建并绑定网关服务、网关服务策略、网关插件等关联依赖，完成策略集与网关的绑定。

取消与AI网关的绑定

删除策略集或为网关更换其他策略集前，需先取消绑定。

1. 在策略集列表中，找到已绑定网关的目标策略集，单击其名称。

2. 在策略集详情页，切换到关联网关页签。

3. 在关联的网关列表中，找到希望解绑的网关。单击操作列的解绑网关。

4. 在确认对话框中，输入网关ARN，然后单击解绑网关按钮。解绑任务将自动解绑并删除网关插件、网关服务策略、网关服务等关联依赖，完成策略集与网关的解绑。

删除策略集

当一个策略集不再需要时，可以将其删除以简化管理。

1. 在策略集列表中，找到目标策略集。

2. 单击操作列的删除策略集。

3. 在弹出的确认对话框中，输入策略集名称，然后单击删除策略集按钮。

查看插件日志

1. 登录 AI 网关控制台。

2. 在左侧导航栏，选择AI网关 > 实例。

3. 在实例列表中，单击已绑定策略集的 AI 网关实例 ID，进入实例详情页。

4. 在左侧导航栏选择插件，在插件列表中单击 AgentIdentity 鉴权。

5. 在插件详情页，切换到日志页签，即可查询鉴权相关日志。

日志字段与查询方式

不同执行模式与鉴权结果对应不同的日志字段，可基于这些字段构造查询语句快速过滤目标日志：

通用查询语句模板如下，将其中的 <ai-gateway-instance-id> 替换为实际的 AI 网关实例 ID，将 <authz_field> 替换为上表中对应的日志字段：

module:wasm and cluster_id:<ai-gateway-instance-id> and (content:agent-identity-oauth or content:agent_identity_oauth or plugin_name:agent-identity-oauth) and content:<authz_field>

日志示例

各场景下的日志结构一致，主要字段含义如下：

• allow：本次请求最终鉴权结果。true 表示允许，false 表示拒绝。

• enforcementMode：策略集在网关上的执行模式。LOG_ONLY 对应观察模式，ENFORCE 对应拦截模式。

• decidingPolicySetArn：决定最终鉴权结果的策略集 ARN。

• reasons：允许或显式拒绝（命中了配置的拒绝策略）的情况下，会显示命中的策略名。拒绝时若该值为空，表示无任何允许策略命中（默认拒绝）。

示例日志如下：

• 观察模式 + 允许访问（authz_observe_allow）

  {
    "authz_observe_allow": {
      "allow": true,
      "costMs": 198,
      "decidingPolicySetArn": "acs:agentidentity:cn-beijing:173305794806****:policyset/<policy-set-name>",
      "enforcementMode": "LOG_ONLY",
      "reasons": ["<policy-name-that-allows-access>"],
      "requestId": "3D53F4DE-810C-5E38-8055-4FB4CC15****"
    }
  }
  

• 观察模式 + 拒绝访问（authz_observe_deny）

  {
    "authz_observe_deny": {
      "allow": false,
      "costMs": 129,
      "decidingPolicySetArn": "acs:agentidentity:cn-beijing:173305794806****:policyset/<policy-set-name>",
      "enforcementMode": "LOG_ONLY",
      "reasons": [],
      "requestId": "ACB16D26-6500-5E5B-966E-659345C2****"
    }
  }

• 拦截模式 + 拒绝访问（authz_trace_deny）

  {
    "authz_trace_deny": {
      "allow": false,
      "costMs": 154,
      "decidingPolicySetArn": "acs:agentidentity:cn-beijing:1733057948067065:policyset/<policy-set-name>",
      "enforcementMode": "ENFORCE",
      "reasons": [],
      "requestId": "A7FC6D61-A922-5AEC-873C-6951F81E****"
    }
  }