版本：3.10.x

权限策略和权限边界

API7 网关通过权限策略和权限边界实现细粒度访问控制。二者都使用相同语法的 JSON 文档表达，并会在处理请求时进行评估，以决定是否允许对特定资源执行特定操作。

本页记录控制面接受的确切 JSON 结构。完整的允许操作和资源目录请参阅权限策略操作和资源。可直接复用和调整的示例请参阅权限策略示例。

概念

权限策略：定义一组 statement 语句的 JSON 文档。每个语句允许或拒绝对特定资源执行特定操作，并可选地受条件约束。权限策略可以附加到一个或多个角色。
权限边界：直接应用于用户的权限策略。用户的有效权限是其角色权限与权限边界的交集：只有当用户角色允许且权限边界也允许时，某个操作才会被允许。权限边界是安全委派的主要机制，例如允许团队负责人管理本部门用户，但不允许其提升权限。

策略文档结构

权限策略通过 Admin API 向 /api/permission_policies 发送包含 PermissionPolicy 对象的 POST 请求来创建。顶层对象包含以下字段：

字段	类型	是否必需	描述
`name`	字符串	是	策略的人类可读名称。
`desc`	字符串	否	描述该策略授予的权限。
`labels`	`map[string]string`	否	附加到策略自身的标签，用于组织和过滤。
`policy_document`	对象	是	实际策略规则，封装在 `policy_document` 对象中。

policy_document 对象包含单个 statement 字段，该字段保存一个语句数组：

{
  "name": "production-readonly",
  "desc": "Read-only access to production gateway groups.",
  "labels": {
    "team": "sre",
    "env": "production"
  },
  "policy_document": {
    "statement": [
      {
        "effect": "allow",
        "resources": [
          "arn:api7:gateway:gatewaygroup/<.*>"
        ],
        "actions": [
          "<.*>Get<.*>"
        ],
        "conditions": {
          "gateway_group_label": {
            "type": "MatchLabel",
            "options": {
              "key": "env",
              "operator": "exact_match",
              "value": "production"
            }
          }
        }
      }
    ]
  }
}

`statement` 字段

policy_document.statement 中的每一项都是一个对象，包含以下字段：

字段	类型	是否必需	描述
`effect`	字符串	是	可为 `"allow"` 或 `"deny"`。
`resources`	字符串数组	是	一个或多个 ARN 风格的资源模式，该语句适用于这些资源。可在 `<...>` 中嵌入正则表达式。
`actions`	字符串数组	是	一个或多个操作名称，该语句适用于这些操作。可在 `<...>` 中嵌入正则表达式。
`conditions`	对象	否	进一步约束语句何时匹配的运行时条件。请参阅条件。

操作

操作使用 <namespace>:<verb><resource-type> 格式，例如：

gateway:GetPublishedService
gateway:CreateConsumer
gateway:DeleteConsumerCredential
iam:InviteUser
iam:UpdateRole
portal:CreateAPIProduct

目前使用三个命名空间：gateway: 用于数据面配置，iam: 用于身份和组织设置，portal: 用于开发者门户资源。完整目录记录在权限策略操作和资源中。

操作支持用尖括号包裹的正则通配符：

<.*> 匹配每个操作。
<.*>Get<.*> 匹配所有命名空间中的每个只读操作。
gateway:<.*>CustomPlugin<.*> 匹配每个自定义插件操作。

资源

资源使用 ARN 风格格式：arn:api7:<namespace>:<resource-type>/<id>[/<sub-resource-type>/<sub-id>]。

各命名空间示例：

命名空间	资源模式	适用于
`gateway`	`arn:api7:gateway:gatewaygroup/<gateway-group-id>`	特定网关组及其顶层资源（证书、全局规则、插件元数据等）
`gateway`	`arn:api7:gateway:gatewaygroup/<gg-id>/service/<svc-id>`	网关组中的特定服务
`gateway`	`arn:api7:gateway:gatewaygroup/<gg-id>/consumer/<username>`	网关组中的特定消费者
`gateway`	`arn:api7:gateway:gatewaysetting/*`	全局网关设置（自定义插件、部署设置）
`gateway`	`arn:api7:gateway:alert/<alert-policy-id>`	特定告警策略
`iam`	`arn:api7:iam:user/<user-id>`	特定用户
`iam`	`arn:api7:iam:role/<role-id>`	特定角色
`iam`	`arn:api7:iam:permissionpolicy/<permission-policy-id>`	特定权限策略
`iam`	`arn:api7:iam:contactpoint/<contact-point-id>`	特定告警联系人
`iam`	`arn:api7:iam:organization/*`	组织级设置（许可证、审计日志、SCIM、SMTP）
`portal`	`arn:api7:portal:portal/<portal-id>`	特定开发者门户实例
`portal`	`arn:api7:portal:portal/<portal-id>/apiproduct/<product-id>`	特定 API 产品
`portal`	`arn:api7:portal:portal/<portal-id>/developer/<developer-id>`	特定开发者
`portal`	`arn:api7:portal:dcrprovider/*`	动态客户端注册提供商

与操作一样，资源也支持 <...> 中的正则通配符。例如：

arn:api7:gateway:gatewaygroup/<.*> 匹配每个网关组。
arn:api7:gateway:gatewaygroup/<.*>/consumer/<.*> 匹配每个网关组中的每个消费者。
arn:api7:iam:user/<.*> 匹配每个用户。

每个操作的有效资源模式完整列表记录在权限策略操作和资源中。

条件

可选的 conditions 字段会进一步约束语句，通常用于要求目标资源带有特定标签。每个条件都有一个用户定义的键（会在界面中显示给审计人员）、一个 type 和一个 options。

支持以下条件类型：

MatchLabel

匹配带有特定标签的资源。这是构建可扩展到大量资源的策略时推荐的方式。

"conditions": {
  "gateway_group_label": {
    "type": "MatchLabel",
    "options": {
      "key": "env",
      "operator": "exact_match",
      "value": "production"
    }
  }
}

MatchLabel 选项：

选项	类型	描述
`key`	字符串	目标资源上的标签键。
`operator`	字符串	`exact_match` 或 `contains_string` 之一。
`value`	字符串	用于比较的标签值。

常见的条件键包括 gateway_group_label、service_label 和 permission_policy_label。你选择的键只用于标识该条件适用的带标签资源类型；它的值必须与 resources 中引用的资源类型匹配。

AllOfStrings

要求上下文中存在列表里的每个字符串。它主要用于按名称强制执行权限边界。

"conditions": {
  "permission_boundaries": {
    "type": "AllOfStrings",
    "options": ["boundary_a", "boundary_b"]
  }
}

`effect` 优先级：`deny` 覆盖 `allow`

当多个语句、策略或角色应用于同一个请求时，API7 网关使用 deny 覆盖 allow 原则：如果任何语句对请求的操作和资源产生 deny，该请求就会被阻止，无论有多少个 allow 语句匹配。请使用显式 deny 语句保护关键操作（例如 iam:UpdateLicense），即使用户持有其他范围较广的角色。

权限边界

权限边界是通过 Admin API（PUT /api/users/{user_id}/boundaries）直接附加到用户的权限策略。它的作用是设置用户无论持有哪些角色都不能超过的最大权限。

假设开发者 John 的角色是 "Development Team Member"，拥有测试网关组的完整访问权限。之后，如果 John 晋升并额外分配了 "Test Engineer" 角色（该角色包含生产环境的完整访问权限），但他的权限边界仍限制在测试网关组，那么 John 不会获得生产环境访问权限，除非显式更新他的权限边界。这使权限边界非常适合强制执行组织约束，即使角色发生变化也能持续生效。

最佳实践

管理大量资源时，优先使用基于标签的条件，而不是硬编码资源 ID。标签可以在不修改策略的情况下扩展。
对敏感用户（承包商、委派管理员）使用权限边界，限制其最大权限。
仅为少数关键操作（许可证更新、角色删除、凭证读取）保留显式 deny 语句，以防止意外过度授权。
应用最小权限原则：从窄范围开始，根据需要再扩展，而不是从宽范围开始。
始终谨慎限定 gateway:CreateGatewayGroup 及类似创建操作；不受约束的创建权限可能被用于创建隔离环境，从而绕过其他控制。

后续步骤

权限策略操作和资源——支持的操作和资源 ARN 完整目录。
权限策略示例——可直接改造的示例策略。
基于角色的访问控制（RBAC）——了解角色、用户和策略如何协同工作。
创建自定义角色——将策略应用到真实角色并分配给用户。
设计自定义角色体系——设计跨团队和环境的可扩展访问模型。
审计日志——跟踪权限策略变更。

概念​

策略文档结构​

statement 字段​

操作​

资源​

条件​

MatchLabel​

AllOfStrings​

effect 优先级：deny 覆盖 allow​

权限边界​

最佳实践​

后续步骤​

概念