Azure AI 搜索中的查询时 ACL 和 RBAC 强制

2025-06-20

查询时访问控制可确保用户仅根据其标识、组成员身份、角色或属性检索他们有权访问的搜索结果。此功能对于安全企业搜索和合规性驱动的工作流至关重要。

Azure Data Lake Storage（ADLS）Gen2 提供了一种访问模型，使细粒度访问控制更易于实现，但前提是您使用推送 API 并发送包含权限元数据以及其他可索引字段的文档时，也可以使用其他数据来源。

要求

权限元数据必须位于 filterable 字符串字段中。不会在查询中使用筛选器，但搜索引擎在内部生成筛选器以排除未经授权的内容。
权限元数据必须由标识访问级别和组或用户 ID 的 POSIX 样式权限或 ADLS Gen2 中的容器的资源 ID（如果使用 RBAC 范围）组成。
对于 ADLS Gen2 数据源，必须在容器级别配置访问控制列表 (ACL) 和/或 Azure 基于角色的访问控制 (RBAC) 角色。可以使用内置索引器或推送 API 在索引中为权限元数据编制索引。
使用 2025-05-01 预览版 REST API 或 Azure SDK 的预发行版包查询索引。此 API 版本支持筛选出未经授权的结果的内部查询。

查询时强制的工作原理

本部分列出了查询时 ACL 强制的操作顺序。操作取决于使用 Azure RBAC 范围还是 Microsoft Entra ID 组或用户 ID。

1.用户权限输入

最终用户应用程序将用户权限作为搜索查询请求的一部分发送。下表列出了 Azure AI 搜索用于实施 ACL 的用户权限的来源：

权限类型	来源
用户ID	来自 `oid` 令牌的 `x-ms-query-source-authorization`
组 ID	使用 Microsoft Graph API 获取的组成员列表
rbacScope	用户对 `x-ms-query-source-authorization` 存储容器拥有的权限

2. 安全筛选器构造

Azure AI 搜索根据提供的用户权限动态构造安全筛选器。如果索引启用了权限筛选器选项，这些安全筛选器将自动追加到查询附带的任何筛选器。

对于 Azure RBAC，权限是资源 ID 字符串的列表。必须在数据源上分配一个 Azure 角色（存储 Blob 数据读取者），以便在授权标头中授予对安全主体令牌的访问权限。如果请求中访问令牌背后的主体没有角色分配，则筛选器将排除文档。

3. 结果筛选

安全过滤器高效地将用户的 userIds、groupIds 和 rbacScope 与搜索索引中每个文档的 ACL 列表进行匹配，以便限制返回的结果，仅限于用户有权访问的内容。请务必注意，每个筛选器都独立应用，如果任何筛选器成功，则文档被视为已授权。例如，如果用户可以通过 userId 访问文档，但不能通过 groupId 访问文档，则文档仍被视为有效，并返回给用户。

局限性

如果 ACL 评估失败（例如图形 API 不可用），服务将返回 5xx 并不返回部分筛选的结果集。
文档可见性需要两者：
- 调用应用程序的 RBAC 角色（授权标头）和
- x-ms-query-source-authorization 携带的用户标识。

查询示例

下面是示例代码中的查询请求的示例。查询令牌将在请求标头中传递。

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-05-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

通过