数据 API 生成器中的授权和角色

数据 API 生成器使用基于角色的授权工作流。任何传入请求，无论是否经过身份验证，都会被分配给一个角色。角色可以是系统角色或用户角色。然后，将分配的角色根据配置中指定的定义权限进行检查，以了解在请求实体上该角色可用的操作、字段和策略。

说明数据 API 生成器如何选择角色并评估请求的权限。

确定用户的角色

没有角色具有默认权限。数据 API 生成器确定角色后，实体 permissions 必须为该角色定义 actions，才能使请求成功。

以下角色评估矩阵适用于 JWT 授权持有者提供方（例如EntraID/AzureAD 和Custom），客户端发送 Authorization: Bearer <token>。

提供的持有者令牌	`X-MS-API-ROLE` 提供	请求的角色存在于令牌 `roles` 声明中	有效角色/成果
否	否	N/A	`Anonymous`
是（有效）	否	N/A	`Authenticated`
是（有效）	是的	否	被拒绝（403 禁止）
是（有效）	是的	是的	`X-MS-API-ROLE` 值
是（无效）	任意	N/A	被拒绝（401 未授权）

若要使用其他角色而不是Anonymous或Authenticated，需要X-MS-API-ROLE标头。

注释

请求可以与经过身份验证的主体中的许多角色相关联。但是，数据 API 生成器在恰好一个有效角色的上下文中评估权限和策略。提供后，标头 X-MS-API-ROLE 将选择使用哪个角色。

提供者说明：

EasyAuth 提供程序（例如， AppService）：可以通过平台注入的标头（例如 X-MS-CLIENT-PRINCIPAL）而不是持有者令牌来建立身份验证。
Simulator：请求被视为经过开发/测试身份验证，而无需验证真实令牌。

系统角色

系统角色是数据 API 生成器识别的内置角色。无论请求者在其访问令牌中表示的角色成员身份如何，系统角色都会自动分配给请求者。有两个系统角色： Anonymous 和 Authenticated。

匿名系统角色

系统 Anonymous 角色分配给未经身份验证的用户执行的请求。如果需要未经身份验证的访问，运行时配置定义的实体必须包含对 Anonymous 角色的权限。

示例：

以下数据 API 生成器运行时配置演示了显式配置系统角色 Anonymous 以包括对 Book 实体的读取访问权限：

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Anonymous",
            "actions": [ "read" ]
        }
    ]
}

当客户端应用程序代表未经身份验证的用户发送访问 Book 实体的请求时，应用不应包含 Authorization HTTP 标头。

经过身份验证的系统角色

经过身份验证的用户执行的请求被分配到系统 Authenticated 角色。

示例：

以下数据 API 生成器运行时配置演示了显式配置系统角色 Authenticated 以包括对 Book 实体的读取访问权限：

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Authenticated",
            "actions": [ "read" ]
        }
    ]
}

用户角色

用户角色是分配给你在运行时配置中设置的标识提供者中的用户的非系统角色。若要使数据 API 生成器在用户角色的上下文中评估请求，必须满足两个要求：

经过身份验证的主体必须包含列出用户角色成员身份的角色声明（例如 JWT roles 声明）。
客户端应用必须包含包含请求的 HTTP 标头 X-MS-API-ROLE ，并将标头的值设置为所需的用户角色。

角色评估示例

以下示例演示对在数据 API 构建器运行时配置中配置的Book实体发出的请求，如下所示：

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

数据 API 构建器在单一有效角色的上下文中评估请求。如果请求经过身份验证且未提供 X-MS-API-ROLE 标头，默认情况下，数据 API 构建器将以系统角色的 Authenticated 上下文来评估请求。

如果客户端应用程序的请求还包括带有X-MS-API-ROLE值的author HTTP 标头，则请求将在author角色的上下文中进行评估。包括访问令牌和 X-MS-API-ROLE HTTP 标头的示例请求：

curl -k -X GET \
  -H 'Authorization: Bearer ey...' \
  -H 'X-MS-API-ROLE: author' \
  https://localhost:5001/api/Book

重要

当提供的访问令牌的 roles 声明不包含标头中列出的 X-MS-API-ROLE 角色时，客户端应用的请求将被拒绝。

权限

权限描述：

谁可以根据角色成员身份对实体发出请求？
用户可以执行哪些作（创建、读取、更新、删除、执行）？
对于某个操作，可以访问哪些字段？
请求返回的结果存在哪些额外限制？

运行时配置文章介绍了定义权限的语法。

重要

单个实体的权限配置中可能定义了多个角色。但是，只有在单个角色的上下文中对请求进行评估：

默认情况下，系统角色 Anonymous 或 Authenticated
当包含时，角色会设置在 HTTP 标头中的 X-MS-API-ROLE。

默认保护

默认情况下，实体没有配置任何权限，这意味着没有人可以访问该实体。此外，数据 API 生成器在运行时配置中未引用数据库对象时会忽略数据库对象。

必须显式配置权限

若要允许对实体进行未经身份验证的访问， Anonymous 必须在实体的权限中显式定义角色。例如， book 将实体的权限显式设置为允许未经身份验证的读取访问：

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

如果希望未经身份验证和经过身份验证的用户都有权访问，请显式授予系统角色（Anonymous 和 Authenticated）的权限。

当读取操作应仅限于经过认证的用户时，应配置以下权限，以拒绝未经认证的请求：

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Authenticated",
    "actions": [ "read" ]
  }]
}

实体不需要且未预配置角色AnonymousAuthenticated的权限。可以在实体的权限配置中定义一个或多个用户角色，所有其他未定义的角色、系统或用户定义的角色都将自动被拒绝访问。

在以下示例中，用户角色 administrator 是实体的唯一定义角色 book 。用户必须是 administrator 角色的成员，并在 X-MS-API-ROLE HTTP 标头中包含该角色才能对 book 实体进行操作。

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

注释

若要在将数据 API 生成器与 Azure Cosmos DB 配合使用时强制实施 GraphQL 查询的访问控制，必须在提供的 @authorize使用该指令。但是，对于 GraphQL 查询中的 GraphQL 突变和筛选器，权限配置仍强制实施访问控制，如前所述。

行动

操作描述角色范围内实体的可访问性。可以单独指定操作或使用星号的通配符快捷方式：*（星号）。通配符快捷方式表示实体类型支持的所有操作。

表和视图：create、、read、 updatedelete
存储过程： execute

有关操作的详细信息，请参阅配置文件文档。

字段访问

可以配置哪些字段是可用于操作访问的。例如，可以设置要从行动中包括和排除的字段。

以下示例阻止 free-access 角色中的用户在 Column3 上执行读取操作。对 Column3 GET 请求（REST 终结点）或查询（GraphQL 终结点）中的引用会导致请求被拒绝：

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

注释

若要在将数据 API 生成器与 Azure Cosmos DB 配合使用时强制实施 GraphQL 查询的访问控制，必须在提供的 @authorize使用该指令。但是，对于 GraphQL 查询中的 GraphQL 突变和筛选器，权限配置仍强制实施访问控制，如下所示。

项目级安全性

使用数据库策略 可以在行级别筛选结果。策略转换为数据库评估的查询谓词，确保用户仅访问已授权记录。

支持的操作	不支持
`read`、`update`、`delete`	`create`、`execute`

注释

Azure Cosmos DB for NoSQL 目前不支持数据库策略。

有关详细的配置步骤、语法参考和示例，请参阅 “配置数据库策略”。

快速示例

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

反馈

此页面是否有帮助？

Last updated on 2026-01-23