数据墙DBW中的角色继承

NOTE

本节描述的 数据墙DBW 2.0 功能当前为预览版，在正式发布前可能会发生变化。相关 2.0 新增内容页面可在对应专题中查看。

角色继承允许你在一个更宽泛的角色上定义一次权限，然后让更具体的角色自动继承该访问权限。如果没有角色继承，你必须在每个实体的每个角色上重复同样的权限块。有了角色继承后，你只需在 anonymous 上定义一次访问权限，所有更宽泛的角色都会自动获得相同访问。

继承链

继承链从权限最少的角色流向权限更高的角色：

named-role → authenticated → anonymous

角色	继承自	说明
命名角色（例如 editor）	authenticated	如果 authenticated 未配置，则从 anonymous 继承
authenticated	anonymous	当没有显式的 authenticated 权限块时生效
anonymous	(none)	继承链底部，没有后备来源

这条继承链意味着：

• 如果某个命名角色没有权限块，数据墙DBW 会查找 authenticated。如果 authenticated 也不存在，则回退到 anonymous。
• 如果 authenticated 没有权限块，数据墙DBW 会使用 anonymous 的权限块。
• 如果 anonymous 也没有权限块，则请求会以 403 Forbidden 被拒绝。

继承如何解析

当数据墙DBW评估一个请求时，它会先判定最终生效角色，然后沿继承链向上查找权限块：

1. 数据墙DBW从请求中识别最终生效角色（通过 X-MS-API-ROLE 标头、令牌声明或默认规则）。
2. 数据墙DBW 在 entities.<name>.permissions 中查找与该角色完全匹配的显式权限块。
3. 如果没有匹配块，数据墙DBW就沿继承链向上查找：authenticated -> anonymous。
4. 找到的第一个匹配权限块就是本次请求使用的权限。
5. 如果链路上没有任何匹配块，数据墙DBW 返回 403 Forbidden。

NOTE

数据墙DBW每次请求只会在一个最终生效角色的上下文中评估权限。角色继承不会把多个角色的权限合并在一起。

示例

最小配置：一个权限块适用于所有角色

在 anonymous 上定义一个 read 权限。所有角色，包括 authenticated 和任意命名角色，都会继承该访问权限。

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

该配置的有效权限如下：

Entity: Book
    Role: anonymous        | Actions: Read
    Role: authenticated    | Actions: Read (inherited from: anonymous)
    Unconfigured roles     | Inherit from: anonymous

分层配置：不同角色拥有不同访问级别

当你需要不同角色拥有不同访问级别时，请显式定义这些角色。继承只会为那些你没有显式配置的角色填补权限。

{
  "entities": {
    "Order": {
      "source": "dbo.orders",
      "permissions": [
        { "role": "anonymous",      "actions": [ "read" ] },
        { "role": "authenticated",  "actions": [ "read", "create" ] },
        { "role": "admin",          "actions": [ "*" ] }
      ]
    }
  }
}

该配置的有效权限如下：

Entity: Order
    Role: anonymous        | Actions: Read
    Role: authenticated    | Actions: Read, Create
    Role: admin            | Actions: Create, Read, Update, Delete
    Unconfigured roles     | Inherit from: authenticated

除 admin 之外的任何命名角色，例如 viewer 或 support，都会从 authenticated 继承，并获得 read 与 create 权限。

无继承：完全阻止访问

如果 anonymous 没有权限块，并且继承链上的其他角色也都没有，那么所有请求都会被拒绝。

{
  "entities": {
    "AuditLog": {
      "source": "dbo.audit_log",
      "permissions": [
        { "role": "admin", "actions": [ "read" ] }
      ]
    }
  }
}

在这个配置中，只有 admin 能访问 AuditLog。authenticated 和 anonymous 没有可继承的权限块，因此这些角色的请求都会被数据墙DBW以 403 Forbidden 拒绝。

IMPORTANT

当某个实体上配置了 authenticated 或命名角色，但身份验证提供程序却是 Unauthenticated 时，数据墙DBW会在启动时发出警告。因为在 Unauthenticated 模式下，这些角色永远不会被激活。有关详细说明，请参阅配置 Unauthenticated 提供程序。

查看最终权限

使用 dab configure --show-effective-permissions 可显示每个实体的最终解析权限，包括哪些角色继承自哪些角色。这是在不真正运行引擎的情况下验证继承是否符合预期的最快方式。

dab configure --show-effective-permissions

你也可以针对某个指定配置文件执行：

dab configure --show-effective-permissions --config my-config.json

输出示例：

Entity: Book
    Role: anonymous        | Actions: Read
    Role: authenticated    | Actions: Read (inherited from: anonymous)
    Unconfigured roles inherit from: anonymous

Entity: Order
    Role: admin            | Actions: Create, Read, Update, Delete
    Role: anonymous        | Actions: Read
    Role: authenticated    | Actions: Read (inherited from: anonymous)
    Unconfigured roles inherit from: authenticated

完整选项请参阅 --show-effective-permissions。

继承与显式权限的取舍

场景	建议
所有角色都应具有相同访问权限	只在 anonymous 上定义一次，让所有角色继承
已认证用户需要比匿名用户更多权限	在 anonymous 上定义 read，在 authenticated 上额外定义 create / update
某个命名角色需要比 authenticated 更宽的权限	显式定义该命名角色；其他角色从 authenticated 继承
某个命名角色需要比 authenticated 更窄的权限	显式定义该命名角色，并只授予更少的动作
某个实体必须完全私有	只授予某个特定命名角色权限；不要定义 authenticated 与 anonymous

相关内容

• 授权概述
• 数据库策略
• 配置 Unauthenticated 提供程序
• --show-effective-permissions 参考
• 2.0 新增内容页面可在对应专题中查看