RBAC 详解

基于角色的访问控制（Role-Based Access Control）是 Code Bird Cloud 的核心授权机制，通过资源、作用域、角色和用户四个维度实现细粒度的权限管理。

资源（Resource）

资源代表系统中的一个 API 服务或受保护的资源集合。每个资源通过一个唯一的 indicator URL 进行标识。

资源属性

属性	类型	说明
name	string	资源名称，用于展示和管理
indicator	string	资源标识符，通常为 API 的基础 URL（如 https://api.example.com）
access_token_ttl	integer	该资源的 Access Token 有效期（秒），默认 3600（1 小时）

资源管理 API

# 获取资源列表
GET /api/v1/resources

# 创建资源
POST /api/v1/resources
{
  "name": "用户管理 API",
  "indicator": "https://api.example.com/users",
  "access_token_ttl": 3600
}

# 获取资源详情
GET /api/v1/resources/:id

# 更新资源
PATCH /api/v1/resources/:id

# 删除资源
DELETE /api/v1/resources/:id

作用域（Scope / Permission）

作用域定义了资源下的具体权限，描述了对资源可执行的操作。作用域隶属于某个资源，命名通常遵循 动作:资源 的格式。

作用域命名规范

示例	说明
read:users	读取用户信息的权限
write:users	创建或修改用户的权限
delete:users	删除用户的权限
read:orders	读取订单信息的权限
manage:settings	管理系统设置的权限

作用域管理

作用域作为资源的子资源进行管理：

# 获取资源下的作用域列表
GET /api/v1/resources/:id/scopes

# 为资源创建作用域
POST /api/v1/resources/:id/scopes
{
  "name": "read:users",
  "description": "读取用户信息"
}

# 删除作用域
DELETE /api/v1/resources/:resourceId/scopes/:scopeId

角色（Role）

角色是一组作用域（权限）的集合。通过将多个作用域绑定到角色，再将角色分配给用户，实现权限的批量管理。

角色类型

类型	说明	适用场景
User	用户角色	分配给普通用户，控制用户对资源的访问权限
MachineToMachine	机器到机器角色	分配给 M2M 应用，用于服务间通信的权限控制

角色管理 API

# 获取角色列表
GET /api/v1/roles

# 创建角色
POST /api/v1/roles
{
  "name": "管理员",
  "description": "拥有系统完整管理权限",
  "type": "User"
}

# 获取角色详情
GET /api/v1/roles/:id

# 更新角色
PATCH /api/v1/roles/:id

# 删除角色
DELETE /api/v1/roles/:id

角色-作用域绑定

将作用域（权限）分配给角色：

# 获取角色的作用域列表
GET /api/v1/roles/:id/scopes

# 设置角色的作用域（完全替换）
PUT /api/v1/roles/:id/scopes
{
  "scope_ids": ["scope_id_1", "scope_id_2", "scope_id_3"]
}

用户-角色绑定

将角色分配给用户，使用户获得对应的权限：

# 获取用户的角色列表
GET /api/v1/users/:id/roles

# 为用户分配角色
POST /api/v1/users/:id/roles
{
  "role_ids": ["role_id_1", "role_id_2"]
}

# 移除用户的角色
DELETE /api/v1/users/:id/roles
{
  "role_ids": ["role_id_1"]
}

权限检查模型

系统的权限检查遵循以下链路：

User（用户）
  │
  ├── Role A（角色 A）
  │     ├── Scope: read:users     ─┐
  │     └── Scope: write:users    ─┤
  │                                │
  └── Role B（角色 B）              │
        ├── Scope: read:orders    ─┤── 用户的有效权限集合
        └── Scope: read:users     ─┘   (去重后的并集)

权限判断规则

1. 获取用户所有角色：查询用户被分配的所有角色
2. 聚合角色权限：收集所有角色绑定的作用域，合并为一个权限集合（取并集）
3. 匹配请求权限：检查请求所需的作用域是否在用户的权限集合中
4. 判断结果：
   • 如果所需作用域存在于用户权限集合中，则允许访问
   • 否则拒绝访问，返回 403 Forbidden

示例

假设系统中有以下配置：

资源：用户管理 API（https://api.example.com/users）

• 作用域：read:users、write:users、delete:users

角色：

• 普通成员：read:users
• 管理员：read:users、write:users、delete:users

用户：

• 张三 -> 普通成员角色 -> 只能读取用户信息
• 李四 -> 管理员角色 -> 可以读取、创建、修改和删除用户

当张三尝试调用删除用户的 API 时，系统检查其权限集合中没有 delete:users，请求被拒绝。