Azure AI 搜索中的查询时 ACL 和 RBAC 实施

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

授权访问取决于索引期间引入的权限元数据。 对于具有内置访问模型的索引器数据源（例如 Azure Data Lake Storage （ADLS） Gen2，索引器可以自动提取每个文档的权限元数据。 对于其他数据源，必须自行组合文档有效负载，并且有效负载必须同时包含内容和关联的权限元数据。 然后使用 推送 API 加载索引。

本文介绍如何设置使用权限元数据筛选结果的查询。

先决条件

• 权限元数据必须位于 filterable 字符串字段中。 不会在查询中使用筛选器，但搜索引擎在内部生成筛选器以排除未经授权的内容。

• 权限元数据必须由标识访问级别和组或用户 ID 的 POSIX 样式权限或 ADLS Gen2 中的容器的资源 ID（如果使用 RBAC 范围）组成。

• 取决于数据源：

  • 对于 ADLS Gen2 数据源，必须在容器级别配置访问控制列表 (ACL) 和/或 Azure 基于角色的访问控制 (RBAC) 角色。
  • 对于 Azure Blob 数据源，必须在容器上分配角色。 可以使用 内置索引器、 知识源或 推送 API 在索引中为权限元数据编制索引。

• 使用 Azure SDK 的最新预览版 REST API 或预览包查询索引或知识源。 此 API 版本支持筛选出未经授权的结果的内部查询。

局限性

• 如果 ACL 评估失败（例如图形 API 不可用），服务将返回 5xx ， 并且不 返回部分筛选的结果集。

• 文档可见性需要两者：

  • 调用应用程序的 RBAC 角色（授权标头）
  • x-ms-query-source-authorization 携带的用户标识

• 与后续请求相比，基于 ACL 的初始查询可能会遇到更高的延迟，因为缓存和权限解析开销。

每个数据源的 ACL 条目限制

访问控制列表（ACL）条目限制定义可以与连接的数据源中的文件、文件夹或项关联的不同权限记录数。 每个条目表示单个用户或组标识以及授予该标识的访问权限（例如，读取、写入或执行）。

Azure AI 搜索功能支持的最大 ACL 条目数因数据源类型而异：

Azure Data Lake Storage Gen2（ADLS Gen2）：每个文件或目录最多可具有 32 个 ACL 条目权限。 在此上下文中，条目表示具有特定权限集的单个主体（用户或组）。 示例：分配“每个人”读取访问权限和“Azure 用户”执行访问权限将计为两个 ACL 条目。

这些限制决定了 Azure AI 搜索在对搜索结果编制索引或筛选时，多大程度上可以满足项级权限。 如果项超出这些 ACL 条目限制，则查询时可能不会强制实施超出限制的权限。

查询时强制的工作原理

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

1.用户权限输入

最终用户应用程序在搜索查询请求中包含查询访问令牌，并且访问令牌通常是用户的标识。 下表列出了 Azure AI 搜索 ACL 强制实施支持的用户权限的来源：

2. 安全筛选器构造

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

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

3. 结果筛选

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

查询示例

下面是 示例代码中的查询请求的示例。 查询令牌将在请求标头中传递。 查询令牌是请求背后的用户或组标识的个人访问令牌。

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

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

用于调查错误结果的高级权限

调试包含权限元数据的查询可能会有问题，因为搜索结果特定于每个用户。 作为开发人员或管理员，您可能需要更高权限来返回与权限元数据无关的结果，以便您可以调查查询返回未经授权内容的问题。

若要进行调查，必须能够：

• 查看最终用户能够基于该用户的权限查看的文档集。

• 查看索引中的所有文档，以调查某些文档对最终用户可能不可见的原因。

可以通过向查询添加自定义标头 x-ms-enable-elevated-read: true来完成这些任务。

提升读取请求的权限

目前，必须 创建自定义角色 才能使用提升的权限运行查询。 添加Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read权限以运行查询。

向查询添加优先读取标头

以下示例是针对搜索索引的查询请求。

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2025-11-01-preview
Authorization: Bearer {AUTH_TOKEN} 
x-ms-query-source-authorization: Bearer {TOKEN} 
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

另请参阅

• 教程：为 ADLS Gen2 权限元数据编制索引

• 在 Azure AI 搜索中使用推送 API 为 ACL 和 RBAC 编制索引

• 使用 ADLS Gen2 索引器引入权限元数据并根据用户访问权限筛选搜索结果

• 使用 Blob 索引器引入 RBAC 范围元数据