角色与自定义角色

每个组织成员都有一个角色，用于控制其可在 AISIX Cloud 控制台和 AISIX Cloud Admin API 中执行的操作。AISIX Cloud 为常见访问模式提供三个内置角色。需要更精细控制的组织可以定义自定义角色，即基于 API 执行权限检查时所使用的同一套资源定义创建的命名权限集合。

组织角色为成员在所有环境中设定基础权限。如果成员需要在某个环境中获得额外访问权限，owner 可以添加环境访问授权，而无需改变其在其他环境中的基础权限。

角色控制谁可以通过控制面配置网关。API Key 设置则单独决定 API Key 可以使用哪些模型和工具，以及其流量适用哪些预算。

内置角色

角色	访问权限
`owner`	完全控制，包括账单、成员角色变更、移除成员和管理 Admin Token。
`admin`	对所有资源具有读写权限。成员角色变更、移除成员和创建 Admin Token 仍仅限 owner 执行。
`member`	对组织资源具有只读权限，不能读取审计事件。

Roles 页面列出每个角色及其实际执行的权限。该页面使用与 API 检查每个请求时相同的权限目录。

自定义角色

自定义角色是针对环境、模型、API Key、安全护栏、预算和审计事件等资源定义的一组命名 read 和 write 权限。它会替换成员的内置基础权限，而不是在其上扩展。例如，只对 environments 授予 read 权限的角色不能列出团队或查看用量。

常见用途包括：

读取审计记录和用量、但不配置任何内容的 auditor 角色。
管理模型、服务提供方密钥和安全护栏、但不能变更成员或账单的 gateway-operator 角色。
以只读为主、仅对一种资源类型（例如预算）授予写权限的角色。

创建和分配

以组织 admin 或 owner 身份打开 Roles，然后选择 New role。
输入永久的小写名称，例如 auditor。成员通过名称引用角色，因此需要不同名称时请创建新角色。
选择角色授予的权限并保存。
以组织 owner 身份在 Members 页面分配该角色。

对于由目录管理的访问权限，自定义角色可以用作默认角色或 SCIM 组到角色映射的目标。请参阅目录同步。

如需修改自定义角色的描述或权限，请打开 Roles 并选择 Edit。如需删除角色，请先清除规则和限制中所述的引用，再选择 Delete。内置角色无法编辑或删除。

环境范围访问

成员的组织角色适用于整个组织。环境访问授权会在一个环境内添加另一个角色。它可以扩展成员的组织角色，但不能缩小其权限。

例如，成员可以保留组织范围的只读访问权限，同时获得生产环境的 admin 授权。该授权会增加对生产环境内资源的写权限，但不会移除成员在其他位置的组织级访问权限。如需降低适用于整个组织的基础权限，请使用自定义组织角色。

成员对环境内资源的有效访问权限由组织角色与该环境的所有授权权限共同组成。
授权在其所属环境之外不生效。其他所有环境中的资源，以及成员、团队、设置、账单和自定义角色等组织级资源，仅由组织角色控制。
授权只覆盖环境内部的资源，不包含环境对象本身。环境范围的 admin 不能重命名或删除环境。
授权可以指向 admin、member 或任意自定义角色，但不能指向 owner。
owner 已拥有全部访问权限，因此不能获得授权。只有 owner 可以编辑成员的授权。
删除环境时，指向该环境的授权也会被删除。

在 Members 页面管理授权：展开成员行中的 Environment access，添加、更改或移除环境与角色的配对，然后保存。

使用 API

使用具有 read 范围的 Admin Token 列出角色和环境访问授权。具有 write 范围的 Token 可以创建、更新或删除角色。只有组织 owner 可以分配角色或替换环境访问授权。

运行示例前，请设置 AISIX Cloud Admin API 基础 URL 和 Token：

# AISIX_CP 包含 /api，末尾不包含斜杠。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

创建并分配自定义角色

创建组织范围的角色，并指定该角色应授予的权限：

curl -sS -X POST "${AISIX_CP}/roles" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auditor",
    "description": "Read-only audit access",
    "permissions": [
      {
        "action": "read",
        "resource": "audit"
      },
      {
        "action": "read",
        "resource": "usage"
      }
    ]
  }'

owner 可以将该角色分配给成员。使用 GET /members 返回的成员 user_id：

export USER_ID="2c7d6e5f-4a3b-4c2d-8e1f-9a0b1c2d3e4f"

curl -sS -X PATCH "${AISIX_CP}/members/${USER_ID}" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"role": "auditor"}'

更新或删除自定义角色

提供 permissions 会替换角色的完整权限集合：

curl -sS -X PATCH "${AISIX_CP}/roles/auditor" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      {
        "action": "read",
        "resource": "audit"
      }
    ]
  }'

清除规则和限制中所述的所有引用后，删除该角色：

curl -sS -X DELETE "${AISIX_CP}/roles/auditor" \
  -H "Authorization: Bearer ${AISIX_TOKEN}"

删除仍被引用的角色会返回 409 ROLE_IN_USE。成员分配和环境授权可以通过 AISIX Cloud Admin API 清除。待处理邀请和目录同步引用目前必须在控制台中清除。

管理环境访问授权

环境访问路由使用 GET /members 返回的成员关系 id，而不是成员的 user_id。替换授权前，请先列出成员的当前授权：

export MEMBER_ID="8f3b2a1c-9d4e-4f6a-b7c8-1e2d3f4a5b6c"

curl -sS "${AISIX_CP}/members/${MEMBER_ID}/role_bindings" \
  -H "Authorization: Bearer ${AISIX_TOKEN}"

owner 可以替换完整的授权集合。每个环境最多出现一次：

curl -sS -X PUT "${AISIX_CP}/members/${MEMBER_ID}/role_bindings" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "bindings": [
      {
        "env_id": "6b1c2c1e-0000-4000-8000-000000000002",
        "role": "admin"
      }
    ]
  }'

发送空的 bindings 数组可移除所有环境访问授权。变更最多可能需要 30 秒才能在控制面副本间传播。

有关响应 Schema 和错误详情，请参阅 AISIX Cloud Admin API 参考。

规则和限制

admin 和 owner 可以创建、编辑和删除自定义角色。向成员分配任何角色仍仅限 owner 执行。
自定义角色不能授予超过内置 admin 角色的权限：仅限 owner 的操作不能授予，目录同步也不能分配 owner。
如果自定义角色已分配给成员或待处理邀请、用作目录同步默认角色或组到角色映射的目标，或者用于环境访问授权，则无法删除该角色。
删除自定义角色前，请重新分配成员、撤销待处理邀请、清除 Directory sync (SCIM) 中 Default role 和 Group → role mappings 下的所有引用，并从 Environment access 授权中移除该角色。
权限变更对持有该角色的所有成员生效，但最多可能需要 30 秒才能在控制面副本间传播。

下一步

如需由身份提供方管理成员和角色分配，请继续阅读 SCIM 目录同步。如需连接为环境资源提供服务的网关，请参阅连接 AISIX 网关。

内置角色​

自定义角色​

创建和分配​

环境范围访问​

使用 API​

创建并分配自定义角色​

更新或删除自定义角色​

管理环境访问授权​

规则和限制​

下一步​