授权概述
授权决定已验证用户在 数据墙DBW 应用中被允许做什么。身份验证负责确认“是谁”，授权则控制“可以访问和修改什么”。
数据墙DBW使用基于角色的授权工作流。任何传入请求，无论是否已身份验证，都会被分配到一个角色。角色可以是系统角色或用户角色。随后，系统会根据配置中定义的权限，判断该角色在请求实体上可执行哪些动作、可访问哪些字段，以及适用哪些策略。
核心授权概念
实体权限
控制实体级 CRUD 操作（创建、读取、更新、删除）。每个角色都可以针对特定实体被授予或拒绝特定动作。
基于角色的访问控制
为用户分配角色，并根据角色成员关系授予权限。角色可帮助你管理拥有相似访问模式的大量用户。
行级安全 (RLS)
基于用户身份或会话上下文过滤数据。用户只能看到自己被授权访问的行，而且这种限制是在数据库层面强制执行的。
API 策略
对 API 响应应用 OData 风格谓词和筛选。策略会根据用户声明和身份自动限制查询结果。
基于声明的授权
通过身份验证令牌中的声明（例如组、角色、自定义属性）来决定访问权限。声明可提供灵活且细粒度的权限决策能力。
工作方式
- 用户完成身份验证，使用数据墙DBW支持的某一种身份验证方式
- 系统从身份验证令牌中提取声明（角色、组、组织等）
- 授权规则根据用户声明和请求资源进行评估
- 根据实体权限、策略和行级安全规则授予或拒绝访问
判定用户角色
任何角色都没有默认权限。一旦数据墙DBW判定出某个角色，实体的 permissions 中必须为该角色定义 actions，请求才能成功。
下表适用于使用 JSON Web Token（JWT）Bearer 提供程序（例如 EntraID / AzureAD 和 Custom）的场景，也就是客户端通过 Authorization: Bearer <token> 发送令牌时的角色判定矩阵。
| 是否提供 Bearer 令牌 | 是否提供 X-MS-API-ROLE | 请求的角色是否存在于令牌 roles 声明中 | 最终角色 / 结果 |
|---|---|---|---|
| No | No | N/A | Anonymous |
| Yes（有效） | No | N/A | Authenticated |
| Yes（有效） | Yes | No | Rejected (403 Forbidden) |
| Yes（有效） | Yes | Yes | X-MS-API-ROLE 的值 |
| Yes（无效） | Any | N/A | Rejected (401 Unauthorized) |
若要使用 Anonymous 或 Authenticated 之外的角色，必须提供 X-MS-API-ROLE 标头。
NOTE
一个请求的已验证主体可能关联多个角色。然而，数据墙DBW在计算权限与策略时，始终只针对一个最终生效角色进行评估。当提供了 X-MS-API-ROLE 标头时，它会决定此次请求使用哪个角色。
提供程序说明：
- EasyAuth 提供程序（例如
AppService）：由平台注入的标头（如X-MS-CLIENT-PRINCIPAL）建立身份验证，而不是依赖 Bearer 令牌。 Simulator：请求在开发 / 测试环境中会被视为authenticated，不会去验证真实令牌。
系统角色
系统角色是数据墙DBW内置识别的角色。无论请求者在访问令牌中具有什么角色成员关系，系统角色都会自动分配给请求者。系统角色只有两个：Anonymous 和 Authenticated。
Anonymous 系统角色
Anonymous 系统角色会分配给未身份验证用户发出的请求。如果希望允许匿名访问，则运行时配置中定义的实体必须包含 Anonymous 角色的权限。
示例
以下数据墙DBW运行时配置显式设置系统角色 Anonymous 对 Book 实体拥有 read 访问权限：
"Book": {
"source": "books",
"permissions": [
{
"role": "Anonymous",
"actions": [ "read" ]
}
]
}当客户端应用代表未身份验证用户访问 Book 实体时，请求中不应包含 Authorization HTTP 标头。
Authenticated 系统角色
Authenticated 系统角色会分配给已身份验证用户发出的请求。
示例
以下数据墙DBW运行时配置显式设置系统角色 Authenticated 对 Book 实体拥有 read 访问权限：
"Book": {
"source": "books",
"permissions": [
{
"role": "Authenticated",
"actions": [ "read" ]
}
]
}用户角色
用户角色是你在运行时配置中设置的身份提供程序里分配给用户的“非系统角色”。为了让数据墙DBW在某个用户角色上下文中评估请求，必须满足两个条件：
- 已验证主体必须包含列出用户角色成员关系的角色声明（例如 JWT 的
roles声明）。 - 客户端应用必须在请求中包含
X-MS-API-ROLEHTTP 标头，并将该标头值设置为目标用户角色。
角色评估示例
以下示例展示了请求访问 Book 实体时，数据墙DBW 运行时配置如下：
"Book": {
"source": "books",
"permissions": [
{
"role": "Anonymous",
"actions": [ "read" ]
},
{
"role": "Authenticated",
"actions": [ "read" ]
},
{
"role": "author",
"actions": [ "read" ]
}
]
}数据墙DBW始终只在单个最终生效角色的上下文中评估请求。如果请求已经通过身份验证且未提供 X-MS-API-ROLE 标头，那么数据墙DBW默认会使用 Authenticated 系统角色来评估请求。
如果客户端请求还包含值为 author 的 X-MS-API-ROLE 标头，那么该请求就会在 author 角色的上下文中被评估。示例如下：
curl -k -X GET \
-H 'Authorization: Bearer ey...' \
-H 'X-MS-API-ROLE: author' \
https://localhost:5001/api/BookIMPORTANT
如果客户端请求所提供访问令牌中的 roles 声明不包含 X-MS-API-ROLE 标头里指定的角色，请求会被拒绝。
权限
权限用于描述：
- 谁可以基于角色成员关系对某个实体发起请求？
- 用户可以执行哪些动作（create、read、update、delete、execute）？
- 某个动作可以访问哪些字段？
- 请求返回的结果还会受到哪些额外限制？
定义权限的语法请参阅实体配置参考页；该专题页可在对应专题中查看。
IMPORTANT
单个实体的权限配置中可以定义多个角色。然而，一次请求只会在一个角色上下文中被评估：
- 默认是系统角色
Anonymous或Authenticated - 如果请求中包含
X-MS-API-ROLE，则使用该标头指定的角色
默认安全
默认情况下，一个实体没有任何权限，也就意味着没有人可以访问它。此外，如果数据库对象没有在运行时配置中被引用，数据墙DBW也会忽略它。
动作
动作用于描述某个角色下实体的可访问能力。动作可以单独指定，也可以使用通配快捷方式：*（星号）。* 代表该实体类型支持的全部动作：
- 表和视图：
create、read、update、delete - 存储过程：
execute
有关动作的更多信息，请参阅实体配置参考页；该页面可在对应专题中查看。
字段访问
你可以配置某个动作可访问哪些字段。例如，你可以为 read 动作设置要 include 和 exclude 的字段。
以下示例禁止 free-access 角色对 Column3 执行读取操作。无论是在 GET 请求（REST 终结点）中，还是在查询（GraphQL 终结点）中引用 Column3，请求都会被拒绝：
"book": {
"source": "dbo.books",
"permissions": [
{
"role": "free-access",
"actions": [
"create",
"update",
"delete",
{
"action": "read",
"fields": {
"include": [ "Column1", "Column2" ],
"exclude": [ "Column3" ]
}
}
]
}
]
}NOTE
当你将数据墙DBW与 Azure Cosmos DB 一起用于 GraphQL 查询时，如果要对 GraphQL 查询强制执行访问控制，你必须在你提供的 GraphQL schema 文件中使用 @authorize 指令。不过，对于 GraphQL mutation 和 GraphQL 查询中的筛选部分，权限配置仍会像这里描述的那样继续生效。
数据库策略（项级安全）
数据库策略允许你在行级别过滤结果。策略会被转换为数据库可执行的查询谓词，从而确保用户只能访问被授权的记录。
| 支持的动作 | 不支持 |
|---|---|
read、update、delete | create、execute |
NOTE
文档数据库场景当前不支持数据库策略。
有关详细配置步骤、语法参考和更多示例，请参阅数据库策略。
快速示例
{
"role": "consumer",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.ownerId eq @claims.userId"
}
}
]
}角色继承
数据墙DBW 2.0 引入了角色继承，因此你不需要在每个角色上重复写相同的权限块。继承链如下：
named-role → authenticated → anonymous- 如果某个实体没有显式配置
authenticated，它会从anonymous继承。 - 如果某个命名角色没有配置，它会从
authenticated继承；如果authenticated也不存在，则继续从anonymous继承。
你可以只在 anonymous 上定义一次权限，而所有更宽泛的角色都会自动获得相同访问权限，无需重复配置。
NOTE
本节描述的 数据墙DBW 2.0 功能当前为预览版，在正式发布前可能会发生变化。相关 2.0 新增内容页面可在对应专题中查看。
{
"entities": {
"Book": {
"source": "dbo.books",
"permissions": [
{ "role": "anonymous", "actions": [ "read" ] }
]
}
}
}在这个配置中，anonymous、authenticated 以及任何未配置的命名角色都可以读取 Book。
你可以使用 dab configure --show-effective-permissions 来显示继承应用后的最终解析权限。
权限必须显式配置
若要允许未身份验证用户访问某个实体，必须在该实体的权限中显式定义 Anonymous 角色。例如，下列 book 实体的权限显式设置为允许未身份验证用户执行读取操作：
"book": {
"source": "dbo.books",
"permissions": [{
"role": "Anonymous",
"actions": [ "read" ]
}]
}当读取操作仅应限于已身份验证用户时，应如下配置权限，此时未身份验证请求将被拒绝：
"book": {
"source": "dbo.books",
"permissions": [{
"role": "Authenticated",
"actions": [ "read" ]
}]
}实体并不要求、也不会默认预配置 Anonymous 与 Authenticated 的权限。你可以只定义一个或多个用户角色；所有其他未定义角色，无论是系统角色还是用户角色，都会被自动拒绝访问。
在下列示例中，用户角色 administrator 是 book 实体唯一被定义的角色。用户必须属于 administrator，并在 X-MS-API-ROLE HTTP 标头中显式声明该角色，才能操作 book 实体：
"book": {
"source": "dbo.books",
"permissions": [{
"role": "administrator",
"actions": [ "*" ]
}]
}NOTE
当你将数据墙DBW与 Azure Cosmos DB 一起用于 GraphQL 查询时，如果要对 GraphQL 查询强制执行访问控制，你必须在你提供的 GraphQL schema 文件中使用 @authorize 指令。不过，对于 GraphQL mutation 和 GraphQL 查询中的筛选，权限配置仍会像前文所述那样生效。
分层安全模型
数据墙DBW使用多层授权模型：
- 实体级：哪些实体和操作可访问
- 策略级：返回哪些数据（基于声明做筛选）
- 行级：数据库通过 RLS 对行做过滤
- API 级：HTTP 标头和请求验证