跳到主要内容
版本:3.10.x

权限策略和权限边界

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

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

概念​

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

策略文档结构​

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

字段类型是否必需描述
name字符串是策略的人类可读名称。
desc字符串否描述该策略授予的权限。
labelsmap[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}]。

各命名空间示例:

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

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

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

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

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

条件​

可选的 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 或 present。present 在标签键存在时匹配,不考虑其值。
value字符串用于比较的标签值。

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

AllOfStrings​

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

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

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: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 及类似创建操作;不受约束的创建权限可能被用于创建隔离环境,从而绕过其他控制。

后续步骤​