Azure AI 搜索 中在查询时实施 ACL 和 RBAC（预览版）

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

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

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

先决条件

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

• 权限元数据必须包含 POSIX 样式的权限，用于标识访问级别和组或用户 ID，或者如果使用 RBAC 作用域，则必须包含 ADLS Gen2 中容器的资源 ID。

• 对于基于 ACL 的强制实施和自定义引入，请将 userIds 和 groupIds 存储为 Microsoft Entra 对象 ID (GUID) 到可筛选字段中。 在查询时，服务将标识 x-ms-query-source-authorization 与存储的 ID 匹配。 有关架构详细信息，请参阅 使用推送 REST API 为文档访问控制列表（ACL）编制索引（预览版）。

• 取决于数据源：

  • 对于 ADLS Gen2 数据源，必须在容器级别配置了访问控制列表 (ACL)和/或 Azure 基于角色的访问控制 (RBAC) 角色。
  • 对于Azure Blob 数据源，必须在容器上分配角色。 可以使用 内置索引器、 知识源或 推送 API 在索引中为权限元数据编制索引。
  • 对于SharePoint数据源，必须配置访问控制列表（ACL）。 可以使用 内置 SharePoint索引器并使用 ACL 引入功能对其进行配置。 还可以使用索引SharePoint知识源并将其配置为强制实施文档级权限。 基于组的权限（包括 Microsoft 365 组）在作为 Entra 对象 ID 引入时受支持。 组扩展是在查询时通过 Microsoft Graph 进行的。

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

限制

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

• ACL 新鲜度取决于引入方法。 若要避免过时的授权决策，请规划每个源如何将权限更改传播到索引：

  • SharePoint 索引器会在每次按计划运行时刷新项级权限的更改。 父级范围（网站、库、列表或文件夹）中的更改如果会由子项继承，则需要重新同步。
  • ADLS Gen2 索引器需要重新同步才能刷新 ACL。
  • 自定义或推送引入需要你重新引入受影响的文档。

• 文档可见性需要两者：

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

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

• 对于已编制索引的 SharePoint 内容，嵌套在 SharePoint 组中的 Microsoft Entra 组不会展开。 Microsoft Entra 的传递性组解析不支持这种混合关系。 请参阅 支持的组关系。

每个数据源的 ACL 条目限制

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

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

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

Microsoft 365中的SharePoint：搜索中的SharePoint数据源支持每个文件最多 1,000 个权限条目。 每个条目都表示该项目权限列表中一个唯一的用户或组分配。 这不同于每个列表或库的总体 唯一权限范围限制 ，这些限制控制可以具有唯一权限的项数。

这些限制决定了 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 访问文档，则文档仍被视为有效，并返回给用户。

查询时的 SharePoint 组

从 2026-05-01-preview REST API 开始，Azure AI 搜索可以在查询时遵循 SharePoint 站点组成员身份，例如所有者、成员、访问者和自定义站点组。 若要启用此方案，索引必须包括：

• sharePointConnectorAppRegistration 属性，该属性引用用于代表用户调用SharePoint的Microsoft Entra应用程序的联合标识凭据。
• 一个用 sharepointSiteUrl: true 属性标记的字段，用于存储每个索引项的SharePoint网站 URL（通常命名为 SharePointSiteUrl，并从 metadata_spo_site_url 源字段填充）。

在查询时，Azure AI 搜索使用每个候选文档上的已注册应用程序和网站 URL 来解析该网站上调用用户的SharePoint 组成员身份。 将解析出的组与存储在 spg: 权限筛选字段中的以 groupIds 为前缀的值进行匹配。 spg: 前缀用于区分 SharePoint 网站组和 Microsoft Entra 组对象 ID，后者存储时不带前缀。

有关配置详细信息和限制，请参阅 Configure SharePoint 组支持。

如果SharePoint权限筛选返回缺失或意外的结果，请参阅SharePoint权限筛选疑难解答。

示例：使用 SharePoint 站点组强制进行查询

请求与标准 ACL 强制查询相同。 搜索服务使用索引的 sharePointConnectorAppRegistration 代表调用方解析 SharePoint 组成员身份。 在 GroupIds 子句中包含 select，即可在响应中看到带有 spg: 前缀的值。

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

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

查询示例

下面是来自 sample 代码的查询请求示例。 该查询令牌是供发起查询的用户使用的 Microsoft Entra 访问令牌。

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-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来完成这些任务。

提升的读取请求的权限

必须具有 搜索索引数据参与者 权限或包含 Elevate 读取权限的 自定义角色 。

查询是数据平面操作，因此自定义角色只能包含原子数据平面权限。 对于自定义角色，请添加 Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read 权限。

向查询添加提升的读取标头

设置权限后，可以运行查询。 以下示例是针对搜索索引的查询请求。

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

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

特定预览版 API 版本中的重要 ACL 功能行为更改

在 REST API 版本之前，早期预览版本2025-11-01-preview2025-05-01-preview2025-08-01-preview在使用服务 API 密钥或授权的 Entra 角色时返回所有文档，即使未提供用户令牌。 如果未正确实现或遵循最佳做法，则未验证用户令牌存在的应用程序可能会无意中向最终用户公开结果。

从 2025 年 11 月开始，此行为已更改：

• 即使在仅使用服务 API 密钥或 Entra 身份验证时，ACL 权限筛选器现在也适用于支持 ACL 的所有版本。
• 如果省略用户令牌，则不会返回受 ACL 保护的内容。
• 为了在故障排除时查看所有文档，使用 REST API 版本 2026-05-01-preview 或更高版本时，必须显式包含 elevated-read 标头。

当应用程序不强制实施令牌验证的最佳做法时，此更新有助于保护内容。

相关内容

• 教程：从 ADLS Gen2 为权限元数据编制索引，并使用权限筛选的结果进行查询（预览版）
• 使用推送 REST API 为文档访问控制列表（ACL）编制索引（预览版）
• 使用 ADLS Gen2 索引器根据用户访问权限引入权限元数据并筛选搜索结果（预览版）
• 使用 Blob 索引器或知识源引入 RBAC 范围元数据
• 使用SharePoint索引器根据用户访问权限引入权限元数据并筛选搜索结果（预览版）