角色与权限

权限配置是数据墙DBW 安全体系的核心。每个实体通过 permissions 数组定义"哪个角色可以对该实体执行哪些操作"。

权限基本结构

{
  "Book": {
    "source": "dbo.Books",
    "permissions": [
      { "role": "anonymous",     "actions": ["read"] },
      { "role": "authenticated", "actions": ["read", "create"] },
      { "role": "editor",        "actions": ["read", "create", "update"] },
      { "role": "admin",         "actions": ["*"] }
    ]
  }
}

每个权限块包含两个核心字段：

字段	必需	说明
role	是	角色名。系统角色（Anonymous、Authenticated）或用户自定义角色
actions	是	操作数组。可以是字符串、对象或混合形式

操作类型

操作字符串

最简单的形式，直接列出操作名：

{ "role": "reader", "actions": ["read"] }

操作对象

需要字段控制或策略时，使用对象形式：

{
  "role": "auditor",
  "actions": [
    {
      "action": "read",
      "fields": {
        "include": ["*"],
        "exclude": ["salary"]
      },
      "policy": {
        "database": "@item.status eq 'published'"
      }
    }
  ]
}

对象形式支持三个子字段：

字段	说明
action	操作名（read、create、update、delete、execute）
fields	字段过滤（include / exclude）
policy	数据库策略（行级过滤表达式）

混合形式

同一角色的不同操作可以使用不同形式：

{
  "role": "editor",
  "actions": [
    { "action": "read", "fields": { "include": ["*"] } },
    "create",
    "update"
  ]
}

操作与数据库对象的对应关系

操作	表	视图	存储过程
read	✓	✓	—
create	✓	若可更新	—
update	✓	若可更新	—
delete	✓	若可更新	—
execute	—	—	✓
*	= CRUD	= CRUD（若可更新）	= execute

权限判定

引擎对每个请求按以下规则判定权限：

请求操作（如 GET /api/Book）→ 映射为 read
                                    ↓
查找当前角色在 Book 上的权限块
  ├── 权限块中有 "read" → 允许
  ├── 权限块中有 "*"   → 允许（通配符匹配）
  ├── 权限块中无匹配项  → 403 Forbidden
  └── 该角色无权限块    → 沿继承链查找 → 仍无 → 403 Forbidden

如果请求的操作被拒绝，引擎返回 403 Forbidden，不区分"角色不存在"和"角色存在但无权执行此操作"。

CLI 配置权限

# 授予单个角色单个操作
dab update Book --permissions "anonymous:read"

# 授予单个角色多个操作
dab update Book --permissions "authenticated:read,create,update"

# 授予多个角色
dab update Book --permissions "anonymous:read" --permissions "authenticated:*"

# 带策略的权限
dab update Order --permissions "customer:read" \
  --policy-database "@item.customerId eq @claims.userId"

CLI 中权限格式为 "角色名:操作1,操作2"。多次指定 --permissions 会添加多个角色块。--permissions 是覆盖式更新——新的值会替换该角色在该实体上的全部现有权限。

常见配置模式

只读开放

匿名用户可以读取，但所有写操作需要认证：

{ "role": "anonymous", "actions": ["read"] },
{ "role": "authenticated", "actions": ["*"] }

分层权限

不同角色有不同的操作范围：

{ "role": "viewer", "actions": ["read"] },
{ "role": "editor", "actions": ["read", "create", "update"] },
{ "role": "admin",  "actions": ["*"] }

仅特定角色可访问

完全私有，只有指定角色能操作：

{ "role": "admin", "actions": ["*"] }

不配置 anonymous 和 authenticated 时，这些系统角色继承不到权限，请求一律被拒绝。

只读存储过程

{ "role": "anonymous", "actions": ["execute"] }

操作分离

读对所有人开放，写只对管理员开放：

{ "role": "anonymous", "actions": ["read"] },
{ "role": "admin",     "actions": ["create", "update", "delete"] }

注意事项

注意事项	说明
角色名大小写	用户角色区分大小写，Editor 和 editor 是不同的角色
权限覆盖	CLI 的 --permissions 是覆盖式更新，不会合并
最小权限原则	只授予角色完成任务所需的最小操作集
存储过程的 *	对存储过程实体，* 仅等于 execute，不会意外暴露增删改
anonymous 与 Unauthenticated	使用 Unauthenticated 认证时所有请求都是 anonymous，authenticated 和命名角色永远不会生效

下一步

• 角色继承 — 减少重复配置。
• 字段级访问控制 — 精确控制字段可见性。
• 授权模型 — 回到授权总览。