# 权限策略和权限边界

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

本页记录控制面接受的确切 JSON 结构。完整的允许操作和资源目录请参阅[权限策略操作和资源](https://docs.apiseven.com/api7-gateway/reference/permission-policy-action-and-resource.md)。可直接复用和调整的示例请参阅[权限策略示例](https://docs.apiseven.com/api7-gateway/reference/permission-policy-examples.md)。

## 概念[​](#概念 "概念的直接链接")

* **权限策略**：定义一组 `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` 字段[​](#statement-字段 "statement-字段的直接链接")

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

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

### 操作[​](#操作 "操作的直接链接")

操作使用 `{namespace}:{verb}{resource-type}` 格式，例如：

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

目前使用三个命名空间：`gateway:` 用于数据面配置，`iam:` 用于身份和组织设置，`portal:` 用于开发者门户资源。完整目录记录在[权限策略操作和资源](https://docs.apiseven.com/api7-gateway/reference/permission-policy-action-and-resource.md)中。

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

* `<.*>` 匹配每个操作。
* `<.*>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/<.*>` 匹配每个用户。

每个操作的有效资源模式完整列表记录在[权限策略操作和资源](https://docs.apiseven.com/api7-gateway/reference/permission-policy-action-and-resource.md)中。

请将 `{gateway-group-id}` 等花括号占位符替换为真实 ID。尖括号在此处含义不同：它们用于包裹正则表达式。成功保存策略并不能证明资源模式匹配预期资源，因此请同时测试一个应当允许的操作和一个应当拒绝的操作。

### 条件[​](#conditions "条件的直接链接")

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

支持以下条件类型：

#### MatchLabel[​](#matchlabel "MatchLabel的直接链接")

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

```
"conditions": {

  "gateway_group_label": {

    "type": "MatchLabel",

    "options": {

      "key": "env",

      "operator": "exact_match",

      "value": "production"

    }

  }

}
```

`MatchLabel` 选项：

| 选项       | 类型   | 描述                                                                                      |
| ---------- | ------ | ----------------------------------------------------------------------------------------- |
| `key`      | 字符串 | 目标资源上的标签键。                                                                      |
| `operator` | 字符串 | `exact_match`、`contains_string` 或 `present`。`present` 在标签键存在时匹配，不考虑其值。 |
| `value`    | 字符串 | 用于比较的标签值。                                                                        |

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

#### AllOfStrings[​](#allofstrings "AllOfStrings的直接链接")

当请求上下文中的列表与所列字符串完全一致时匹配：与顺序无关，不能缺少，也不能多出。它与 `permission_boundaries` 键配合使用，其选项为权限策略 ID，用于控制可以为用户设置哪些权限边界。

```
"conditions": {

  "permission_boundaries": {

    "type": "AllOfStrings",

    "options": ["boundary_a", "boundary_b"]

  }

}
```

## `effect` 优先级：`deny` 覆盖 `allow`[​](#effect-优先级deny-覆盖-allow "effect-优先级deny-覆盖-allow的直接链接")

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

## 权限边界[​](#权限边界 "权限边界的直接链接")

权限边界是直接附加到用户的现有权限策略。请先创建策略，再通过 `PUT /api/users/{user_id}/boundaries` 附加它，并发送策略 ID 数组。无论用户分配了哪些角色，边界都会限制其权限上限。

要查看用户附加的策略，请读取 `GET /api/users/{user_id}` 响应中的 `boundaries` 字段。没有单独的边界读取端点。

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

## 委派用户管理[​](#委派用户管理 "委派用户管理的直接链接")

你可以让团队负责人管理本团队的用户，而不必把他设为管理员。要安全地做到这一点，必须依靠权限边界，因为管理用户和权限的操作不受执行者自身权限的限制。

### IAM 写操作等同于管理员权限[​](#iam-写操作等同于管理员权限 "IAM 写操作等同于管理员权限的直接链接")

以下操作会改变用户被允许执行的操作：

* `iam:UpdateUserRole`：为用户分配角色。
* `iam:UpdateRole`：修改自定义角色附加的权限策略。
* `iam:CreatePermissionPolicy` 和 `iam:UpdatePermissionPolicy`：创建或改写权限策略。

API7 网关不会检查通过这些操作授予的权限是否超出授予者自身的权限，也不会阻止用户修改自己的角色。持有其中任一操作的用户可以把任何权限授予其他用户或自己，最高可达内置的 Super Admin 角色。

能够设置上限的是权限边界。用户的有效权限是其角色权限与权限边界的交集，这同样适用于用户自己执行的 IAM 操作。如果用户的权限边界不允许某个操作，即使用户给自己分配了允许该操作的角色，也无法执行该操作。请把持有 IAM 写操作且没有权限边界的用户视为 Super Admin。

另有两个操作会直接移除这一上限：`iam:UpdateUserBoundary` 会替换用户的权限边界；`iam:DeletePermissionPolicy` 会删除策略，并将其从所有以它为权限边界的用户上移除。

### 配置委派用户管理员[​](#配置委派用户管理员 "配置委派用户管理员的直接链接")

以下配置让委派人可以邀请用户，并为带有 `team: payments` 标签的用户分配角色，但无法获得 Super Admin 权限。该配置使用两个权限策略作为权限边界：

* **权限边界 B**：委派人邀请的每个用户都带有该边界。它只允许这些用户需要的业务操作，不允许任何 IAM 写操作。

* **权限边界 D**：委派人自己带有该边界。它只允许以下操作：

  <!-- -->

  * 对所有用户执行 `iam:InviteUser`，并使用 `permission_boundaries` 条件要求权限边界恰好为 B。这样，只有当邀请请求（`POST /api/invites`）的 `boundaries` 字段只列出权限边界 B 时，请求才会被允许，因此无论委派人为被邀请用户设置什么标签，每个被邀请用户都带有 B。
  * 对通过 `user_label` 条件选定的用户执行 `iam:UpdateUserRole`，以及可选的 `iam:UpdateUser`。
  * 委派人需要的业务操作。

权限边界 D 不得允许 `iam:UpdateUserBoundary`、`iam:CreatePermissionPolicy`、`iam:UpdatePermissionPolicy`、`iam:DeletePermissionPolicy`、`iam:CreateRole` 或 `iam:UpdateRole`。委派人的角色必须允许与权限边界 D 相同的操作，因为只有二者都允许时，操作才会被允许。最简单的做法是把同一个权限策略既附加到委派人的角色，又设置为委派人的权限边界。

以下权限策略既作为委派人的角色策略，也作为权限边界 D。请将 `{boundary_b_id}` 替换为权限边界 B 的 ID，并将最后一个语句替换为委派人需要的业务操作：

```
{

  "name": "payments-user-manager",

  "desc": "Invite users with boundary B and manage the roles of users labelled team=payments.",

  "policy_document": {

    "statement": [

      {

        "effect": "allow",

        "resources": [

          "arn:api7:iam:user/<.*>"

        ],

        "actions": [

          "iam:InviteUser"

        ],

        "conditions": {

          "permission_boundaries": {

            "type": "AllOfStrings",

            "options": ["{boundary_b_id}"]

          }

        }

      },

      {

        "effect": "allow",

        "resources": [

          "arn:api7:iam:user/<.*>"

        ],

        "actions": [

          "iam:GetUser",

          "iam:UpdateUserRole",

          "iam:UpdateUser"

        ],

        "conditions": {

          "user_label": {

            "type": "MatchLabel",

            "options": {

              "key": "team",

              "operator": "exact_match",

              "value": "payments"

            }

          }

        }

      },

      {

        "effect": "allow",

        "resources": [

          "arn:api7:iam:role/<.*>"

        ],

        "actions": [

          "iam:GetRole"

        ]

      },

      {

        "effect": "allow",

        "resources": [

          "arn:api7:gateway:gatewaygroup/<.*>"

        ],

        "actions": [

          "gateway:Get<.*>"

        ],

        "conditions": {

          "gateway_group_label": {

            "type": "MatchLabel",

            "options": {

              "key": "team",

              "operator": "exact_match",

              "value": "payments"

            }

          }

        }

      }

    ]

  }

}
```

`iam:GetUser` 让委派人可以看到其范围内的用户，因为用户列表只显示调用者有权获取的用户。`iam:GetRole` 让委派人可以看到可分配的角色。二者都是只读操作。

在此配置下，委派人可以为其范围内的用户分配任何角色（包括 Super Admin），但该用户的有效权限仍不会超出权限边界 B。如果委派人自己也在其标签范围内，他也可以为自己分配角色，但他自己的有效权限仍不会超出权限边界 D。

### 委派人范围内的每个用户都必须带有权限边界[​](#委派人范围内的每个用户都必须带有权限边界 "委派人范围内的每个用户都必须带有权限边界的直接链接")

API7 网关没有针对被修改用户当前权限边界的条件，也没有限制可授予哪些角色或权限策略的条件。委派人能为哪些用户分配角色，只由 `user_label` 条件决定。

因此，只有当委派人标签范围内的每个用户都带有权限边界时，该配置才是安全的。如果某个没有权限边界的用户匹配该标签，委派人就可以为其分配 Super Admin 角色，使其成为不受限制的 Super Admin。例如，以下情况会让这样的用户进入范围：

* 管理员误将范围标签添加到一个没有权限边界的用户上。
* 用户通过 SSO 登录（例如 CAS）创建，而对应的登录选项没有映射任何权限边界，因此该用户进入范围时没有权限边界。

在为委派人授予角色之前，以及每次修改用户标签或 SSO 登录选项时，请确认每个匹配委派人 `user_label` 条件的用户都带有权限边界。

## 最佳实践[​](#最佳实践 "最佳实践的直接链接")

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

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* [权限策略操作和资源](https://docs.apiseven.com/api7-gateway/reference/permission-policy-action-and-resource.md)——支持的操作和资源 ARN 完整目录。
* [权限策略示例](https://docs.apiseven.com/api7-gateway/reference/permission-policy-examples.md)——可直接改造的示例策略。
* [基于角色的访问控制（RBAC）](https://docs.apiseven.com/api7-gateway/security-and-compliance/role-based-access-control.md)——了解角色、用户和策略如何协同工作。
* [创建自定义角色](https://docs.apiseven.com/api7-gateway/how-to-guides/ops/create-custom-role.md)——将策略应用到真实角色并分配给用户。
* [设计自定义角色体系](https://docs.apiseven.com/api7-gateway/how-to-guides/ops/design-custom-role-system.md)——设计跨团队和环境的可扩展访问模型。
* [审计日志](https://docs.apiseven.com/api7-gateway/security-and-compliance/audit-logs.md)——跟踪权限策略变更。
