Azure AI 搜索中的文档级访问控制

Azure AI 搜索支持文档级访问控制，使组织能够从数据引入到查询执行，在文档级别强制实施精细权限。 此功能对于构建以数据支撑的安全AI代理系统、检索增强生成（RAG）应用程序及需要文档级授权检查的企业搜索解决方案至关重要。

文档级访问控制的方法

Azure AI 搜索提供了四种强制实施文档级权限的主要方法，每个方法都适合不同的数据源和标识模型。

选择方法

使用以下条件确定最适合数据源、标识模型和符合性要求的方法。

使用筛选器进行安全修整的模式

对于无法实现原生 ACL/RBAC 范围集成的场景，建议使用安全字符串筛选器根据排除条件来过滤结果。 该模式包括以下组件：

• 若要存储用户或组标识，请在索引中创建字符串字段。
• 使用包含关联 ACL 的源文档加载索引。
• 在查询逻辑中包含用于匹配字符串的筛选器表达式。
• 查询时获取来电者的身份信息。
• 将调用方的标识作为筛选器字符串传入。
• 结果会被裁剪，以排除任何不包含用户或组身份字符串的匹配项。

可以使用推送或拉取模型 API。 由于此方法与 API 无关，因此只需确认索引和查询是否具有有效的字符串（标识），才能执行过滤步骤。

此方法适用于具有自定义访问模型或非Microsoft安全框架的系统。 有关此方法的详细信息，请参阅 用于在 Azure AI 搜索中修整结果的安全筛选器。

针对类似 POSIX 的 ACL 和 RBAC 范围权限的原生支持模式（预览版）

原生支持是基于 Microsoft Entra 用户和组，以及您希望编制索引和查询的文档。

Azure Data Lake Storage （ADLS） Gen2 容器支持容器和文件上的 ACL。 对于 ADLS Gen2，当使用 ADLS Gen2 索引器 或 Blob 知识源（支持 ADLS Gen2） 以及预览 API 进行内容摄取时，原生支持在文档级别保留 RBAC 范围。 对于使用 Azure Blob 索引器 或知识源的 Azure Blob，RBAC 范围保留位于容器级别。

对于 ACL 保护的内容，我们建议优先使用组访问来代替单个用户访问，以便于管理。 该模式包括以下组件：

• 从具有 ACL 分配的文档或文件开始。
• 在索引中启用权限筛选器。
• 将权限筛选器 添加到索引中的字符串字段。
• 将具有关联 ACL 的源文档加载到索引中。
• 查询索引，并在请求标头中添加 x-ms-query-source-authorization 。

客户端应用通过 搜索索引数据读取者 或 搜索索引数据参与者 角色接收对索引的读取权限。 查询时的访问权限由索引内容中的用户或组权限元数据确定。 包含权限筛选器的查询会将用户或组令牌作为请求头中的 x-ms-query-source-authorization 传递。 在查询时使用权限筛选器时，Azure AI 搜索会检查以下两项：

• 首先，它会检查 搜索索引数据读取者 权限，允许客户端应用程序访问索引。

• 其次，在请求的额外令牌的基础上，它会检查搜索结果中返回的文档的用户或组权限，排除任何不匹配的文档。

若要将权限元数据引入索引，可以使用推送模型 API，将任何 JSON 文档推送到搜索索引，其中有效负载包括一个字符串字段，为每个文档提供类似于 POSIX 的 ACL。 此方法与安全修整之间的重要区别在于，索引和查询中的权限筛选器元数据被识别为Microsoft Entra ID 身份验证，而安全修整解决方法是简单的字符串比较。 此外，还可以使用 Graph SDK 检索标识。

如果数据源为 Azure Data Lake Storage （ADLS） Gen2 ，并且代码调用用于索引的预览 API，也可以使用拉取模型（索引器）API。

在数据引入过程中检索 ACL 权限元数据（预览版）

获取 ACL 权限的方式因是推送文档负载还是使用 ADLS Gen2 索引器而异。

开始使用提供该功能的预览 API：

• 2026-05-01-preview REST API
• 适用于 Python 预发行版包的 Azure SDK。 检查更改日志，了解支持 ACL 和 RBAC 范围引入的最新预览版本。
• .NET 的 Azure SDK 预发行包。 检查更改日志，了解支持 ACL 和 RBAC 范围引入的最新预览版本。
• Java 版 Azure SDK 预发行包。 检查更改日志，了解支持 ACL 和 RBAC 范围引入的最新预览版本。

对于推送模型方法：

1. 确认索引架构是使用预览版或预发行版 SDK 创建的，并且该架构具有权限筛选器。
2. 请考虑使用 Microsoft Graph SDK 获取组或用户标识。
3. 使用 索引文档 或等效的 Azure SDK API 将文档及其关联的权限元数据推送到搜索索引中。

对于拉取模型 ADLS Gen2 索引器方法或 Blob (ADLS Gen2) 知识来源：

1. 使用 ADLS Gen2 访问控制模型验证目录中的文件是否受到保护。
2. 使用 Indexers - Create（REST API）、Knowledge Sources - Create（REST API）或等效Azure SDK API 创建索引器、索引和数据源。

在查询时强制实施文档级权限

基于令牌的查询执行控制是一种横切能力，适用于类 POSIX 的 ACL/RBAC 作用域。 使用原生基于令牌的查询时，只要文档 ACL 元数据已同步到索引，Azure AI 搜索 就会对每个请求验证调用方的Microsoft Entra 令牌，并将结果集裁剪为仅包含调用方根据文档 ACL 有权读取的文档。

当你通过 x-ms-query-source-authorization 标头在查询请求中附加用户令牌时，Azure AI 搜索：

1. 从令牌中提取用户声明、组声明和作用域声明。
2. 将这些声明与与索引文档一起存储的权限元数据（ACL 条目、RBAC 范围、Purview 标签分配或SharePoint ACL）进行比较。
3. 仅返回同步的权限元数据授予调用方访问权限的文档。

查询时强制实施会根据已存储在索引中的权限元数据来评估调用方的 Microsoft Entra 声明。 源系统（Microsoft Entra组成员身份、ADLS Gen2 ACL、Purview 标签分配）中的权限更改仅在元数据通过特定于源的机制同步到索引后才会反映在搜索结果中，例如，后续索引器运行、推送 API 更新或 Purview 驱动的刷新。 对于 SharePoint，从 2026-05-01-preview REST API 版本开始，具有唯一权限的项目上的 ACL 更改会在索引器每次成功运行时被增量检测到，而从父作用域（网站、库、列表或文件夹）继承的更改则需要显式刷新。

有关端到端查询实现步骤，请参阅 Azure AI 搜索 中查询时 ACL 和 RBAC 实施。

文档级访问控制的优点

Azure AI 搜索中的本机文档级访问控制在应用程序端筛选方面具有具体优势：

• 消除自定义权限代码： 无需在应用程序中实现嵌套组解析、多级 ACL 遍历或查询后修整。 Azure AI 搜索处理查询执行期间的比较和筛选。
• 具有现有符合性控制：重用Microsoft Entra、Microsoft Purview和SharePoint权限元数据有助于使搜索结果与源标识系统保持一致。 查看每个源的权限同步模型以了解其限制。
• 在每次 ACL 同步后遵循源权限：对于基于令牌的方法（ACL、RBAC 范围、Purview 标签、SharePoint ACL），查询时的强制执行使用的是文档中记录的源特定同步机制（索引器运行、Push API 更新或 Purview 刷新）已写入索引的权限元数据。
• 与查询后裁剪相比，可提升性能： 在搜索流程中进行筛选，比将更大的结果集加载到应用程序中再进行裁剪更快，尤其是在查询量较高时。
• 恢复现有标识基础结构： Microsoft Entra和SharePoint标识仍然是访问决策的真相来源，从而减少标识重复和维护并行权限存储的操作开销。

教程和示例

使用更多文章和示例详细了解 Azure AI 搜索中的文档级访问控制。

• 教程：使用索引器为 ADLS Gen2 权限元数据编制索引
• azure-search-rest-samples/acl
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API
• azure-search-python-samples/Quickstart-Document-Permissions-Pull-API

相关内容

• 如何使用推送 API 为文档级权限编制索引
• 如何使用 ADLS Gen2 索引器为文档级权限编制索引
• 如何使用索引器为敏感度标签编制索引
• 如何使用基于 Microsoft Entra 令牌的权限进行查询