Azure AI 搜索支持文档级访问控制，使组织能够从数据引入到查询执行，在文档级别强制实施精细权限。 此功能对于构建基于数据安全的 AI 代理系统、Retrieval-Augmented 代（RAG）应用程序以及需要进行文档级别授权检查的企业搜索解决方案至关重要。
文档级访问控制的方法
| 方法 | Description |
|---|---|
| 安全筛选器 | 字符串比较。 应用程序将用户或组标识作为字符串传入，该字符串将填充查询的筛选器，不包括字符串上不匹配的任何文档。 安全筛选器是实现文档级访问控制的技术。 此方法未绑定到 API，因此可以使用任何版本或包。 |
| ACL /RBAC 范围（预览版） | 查询令牌背后的 Microsoft Entra ID 安全主体与搜索结果中返回的文档的权限元数据进行比较，排除任何权限不匹配的文档。 访问控制列表（ACL）权限适用于 Azure Data Lake Storage（ADLS） Gen2 目录和文件。 基于角色的访问控制（RBAC）范围适用于 ADLS Gen2 内容和 Azure Blob。 文档级基于标识的访问的内置支持处于预览状态，可在 REST API 和提供此功能的预览版 Azure SDK 包中使用。 请务必检查 SDK 包更改日志 ，了解功能支持的证据。 |
使用筛选器进行安全修整的模式
对于无法进行原生 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：
- 2025-11-01-preview REST API
- 用于 Python 的 Azure SDK 预发行版包
- 用于 .NET 的 Azure SDK 预发行版包
- 用于 Java 的 Azure SDK 预发行版包
对于推送模型方法：
- 确保索引架构也是使用预览版或预发行版 SDK 创建的，并且该架构具有权限筛选器。
- 请考虑使用 Microsoft Graph SDK 获取组或用户标识。
- 使用 索引文档 或等效的 Azure SDK API 将文档及其关联的权限元数据推送到搜索索引中。
对于拉取模型 ADLS Gen2 索引器方法或 Blob (ADLS Gen2) 知识来源：
- 使用 ADLS Gen2 访问控制模型验证目录中的文件是否受到保护。
- 使用 创建索引器 或等效的 Azure SDK API 创建索引器、索引和数据源。
在查询时强制实施文档级权限
使用原生令牌查询，Azure AI 搜索会验证用户的 Microsoft Entra 令牌，并将结果集进行过滤，仅包含用户有权访问的文档。
可以通过将用户的 Microsoft Entra 令牌附加到查询请求来实现自动修整。 有关详细信息，请参阅 Azure AI 搜索中的查询时 ACL 和 RBAC 强制实施。
文档级访问控制的优点
文档级访问控制对于保护 AI 驱动的应用程序中的敏感信息至关重要。 它可帮助组织构建与其访问策略保持一致的系统，从而降低暴露未经授权的或机密数据的风险。 通过将访问规则直接集成到搜索管道中，AI 系统可以提供以安全和授权信息为依据的响应。
通过将权限强制执行卸载到 Azure AI 搜索，开发人员可以专注于构建高质量的检索和排名系统。 此方法有助于减少处理嵌套组、编写自定义筛选器或手动剪裁搜索结果的需求。
Azure AI 搜索中的文档级权限提供了一个结构化框架，用于强制实施符合组织策略的访问控制。 通过使用基于 Azure Entra 的 ACL 和 RBAC 角色，组织可以创建支持可靠合规性并提升用户信任的系统。 这些内置功能减少了自定义编码的需求，为文档级安全性提供了标准化方法。
教程和示例
使用更多文章和示例详细了解 Azure AI 搜索中的文档级访问控制。
- 教程：使用索引器为 ADLS Gen2 权限元数据编制索引
- azure-search-rest-samples/Quickstart-ACL
- azure-search-python-samples/Quickstart-Document-Permissions-Push-API
- azure-search-python-samples/Quickstart-Document-Permissions-Pull-API