你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

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

文档级访问控制的方法

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

方法 描述
安全筛选器 字符串比较。 应用程序将用户或组标识作为字符串传入，该字符串将填充查询的筛选器，不包括字符串上不匹配的任何文档。

安全筛选器是实现文档级访问控制的技术。 此方法未绑定到 API，因此可以使用任何版本或包。
POSIX 类 ACL/RBAC 范围（预览） 将查询令牌所对应的 Microsoft Entra 安全主体与搜索结果中返回的文档的权限元数据进行比对，并排除任何权限不匹配的文档。 访问控制列表 （ACL） 权限适用于 Azure Data Lake Storage （ADLS） Gen2 目录和文件。 基于角色的访问控制（RBAC）范围适用于 ADLS Gen2 内容和Azure blob。

对在文档级别进行基于标识的访问的内置支持已在预览版中提供，该功能在 REST API 及 Azure SDK 预览版包中可用。 有关功能支持的证据，请查看 SDK 版本支持详细信息。
Microsoft Purview敏感度标签（预览版） 索引器从支持的数据源（Azure Blob 存储、ADLS Gen2、oneLake 中的Microsoft 365 SharePoint）提取Microsoft Purview中定义的敏感度标签。 这些标签作为元数据存储，并在查询时进行评估，以根据 Microsoft Entra 令牌和 Purview 策略分配来强制执行用户访问。 标签还通过 知识源 和 代理检索响应浮出水面，允许使用知识库的 AI 代理和聊天应用接收相同的标签感知筛选。 此方法将Azure AI 搜索授权与企业的Microsoft 信息保护模型保持一致。
Microsoft 365 ACL 中的SharePoint（预览版） Azure AI 搜索索引器从受支持的SharePoint内容中提取权限元数据，并将其用于查询时访问检查。 有关支持的内容、主体、组关系、同步行为和权限，请参阅使用SharePoint索引器引入权限元数据。

对于已编制索引的知识源，ingestionPermissionOptions 不能与 assetStore 结合使用。 因此，启用原生文档级权限引入时，图像服务（预览版）不可用。

选择方法

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

Scenario 建议的方法 为什么
自定义身份系统、非微软安全框架，或任何推送模式索引。 安全筛选器 不依赖 API，正式可用，并基于简单的字符串匹配。
ADLS Gen2 或 Azure Blob 存储中具有现有 ACL 或 RBAC 分配的内容。 类似于 POSIX 的 ACL/RBAC 范围 原生 Microsoft Entra 集成；查询时强制执行基于由文档中说明的同步机制写入索引的权限元数据。
已受到 Microsoft Purview 信息保护策略管理的企业内容。 Microsoft Purview 敏感度标签 在 Azure AI 搜索 中复用集中式分类和策略分配。
从Microsoft 365中的SharePoint（库、列表、ASPX 网站页面）中源的内容。 Microsoft 365 ACL 中的SharePoint 遵从 SharePoint 原生权限，包括 SharePoint 站点组。

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

对于原生 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 保护的内容，为便于管理，应优先使用组访问权限，而非单个用户访问权限。 该模式包括以下组件：

客户端应用通过 搜索索引数据读取者 或 搜索索引数据参与者 角色接收对索引的读取权限。 查询时的访问权限由索引内容中的用户或组权限元数据确定。 包含权限筛选器的查询会将用户或组令牌作为请求头中的 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：

对于 推送模型方法：

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

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

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

如果技能组将文档块化（例如使用文本拆分技能进行集成向量化），权限元数据字段将从索引器字段映射移动到索引投影。 请参阅 “选择填充 ACL 字段的位置”。

Microsoft 365基本 ACL 权限引入中的SharePoint模式（预览版）

对于索引SharePoint内容，Azure AI 搜索可以将源权限存储为元数据，并使用它们筛选查询结果。 你可以通过 Microsoft 365 中的 SharePoint 索引器以及最新的 REST API 或等效的预览版 SDK 包，以预览版方式访问此功能。

有关权限要求、支持的组关系、权限同步和限制，请参阅使用SharePoint索引器引入权限元数据。

如果技能组将文档拆分成块（例如，使用文本拆分技能进行集成矢量化），ACL 字段将从索引器字段映射移动到索引投影。 请参阅 “选择填充 ACL 字段的位置”。

Microsoft Purview敏感度标签的模式（预览版）

启用标签引入时，Azure AI 搜索从支持的数据源中提取敏感度元数据。 这些数据源包括Azure Blob 存储、Azure Data Lake Storage Gen2（ADLS Gen2）、Microsoft 365中的SharePoint和Microsoft OneLake。 提取的标签与文档内容一起存储在索引中。

在查询时，Azure AI 搜索检查每个文档的敏感度标签、用户的Microsoft Entra令牌以及组织的 Purview 策略以确定访问权限。 仅当用户的标识和基于标签的权限允许在配置的 Purview 策略下访问时，系统才会返回文档。

此模式包括以下组件：

  • 使用最新的预览版 REST API 或支持 Purview 标签引入的预览 SDK 配置 索引、 数据源和 索引器 （出于计划目的）。
  • 在搜索服务上启用 系统分配的托管标识 。 Purview 标签提取功能不支持用户分配的托管标识——服务自身的标识必须具有更高的 Purview 权限。 然后，让租户全局管理员或特权角色管理员授予所需的访问权限，以允许搜索服务使用Microsoft Purview进行身份验证并提取标签元数据。
  • 在编制索引之前将敏感度标签应用于文档，以便系统可以在引入期间识别和保留它们。
  • 在查询时，通过标头x-ms-query-source-authorization将有效的Microsoft Entra令牌附加到每个查询请求。 Azure AI 搜索评估令牌和关联的标签元数据，以强制实施基于标签的访问控制。

Purview 敏感度标签强制实施仅限于单租户方案，需要 RBAC 身份验证。 在预览版期间，仅支持通过 REST API 和 Azure SDK 使用。 自动完成和建议 API 目前不适用于已启用 Purview 的索引。

敏感度标签的显示位置

必须先将标签元数据同步到索引中，然后系统才能在查询时强制实施标签，或者在检索响应中返回标签。 本节中所述的两个消耗路径都取决于此同步步骤。 可以通过直接针对受支持的数据源配置Azure AI 搜索索引器，或者在创建知识源时启用等效的引入选项来同步标签。 在这两种情况下，你的环境必须满足 敏感标签元数据同步配置先决条件（搜索服务上的托管标识、RBAC 以及所需的Microsoft Purview和数据源权限）。 有关端到端索引器设置，请参阅 使用Azure AI 搜索索引器引入Microsoft Purview敏感度标签。 对于知识来源驱动的数据引入，请将 ingestionPermissionOptions 设置为在sensitivityLabel期间包含 。

同步标签后，两个查询路径使用相同的索引标签元数据。 选择与应用程序调用 Azure AI 搜索的方式相匹配的路径：

  • 直接查询 API（/docs/search）：在 x-ms-query-source-authorization 中附加用户的 Microsoft Entra 令牌。 管理员还可以为可审计调查发出提升读取权限请求。 有关设置和示例，请参阅 Microsoft Purview 敏感度标签的查询时强制。

  • 知识来源和智能体检索 (MCP)：将 ingestionPermissionOptions 设置为包含知识来源上的 sensitivityLabel。 客户端可用于显示横幅和策略执行的检索操作和 MCP knowledge_base_retrieve 工具返回每个引用 sensitivityLabelInfo 和响应级别 metadata.responseSensitivityLabelInfo。 有关设置，请参阅 创建知识源 并 检查检索响应中的敏感度标签元数据。

如果知识源指向分块索引（例如通过集成向量化或自定义文本拆分技能填充的索引），技能组还必须 将敏感度标签投影到每个区块行。 如果没有此投影，则不会筛选区块级引用。

有关详细信息，请参阅 使用Azure AI 搜索索引器引入Microsoft Purview敏感度标签。

在查询时强制实施文档级权限（预览版）

基于令牌的查询强制执行是一种跨领域能力，适用于类 POSIX ACL 和 RBAC 范围、Microsoft Purview 敏感度标签，以及 Microsoft 365 中的 SharePoint ACL 模式。 通过使用基于原生令牌的查询，Azure AI 搜索 会对每个请求验证调用方的Microsoft Entra 令牌，并将结果集限制为仅包含调用方根据文档 ACL 有权读取的文档，前提是文档 ACL 元数据已同步到索引中。

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

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

查询时强制会根据已存储在索引中的权限元数据来评估调用方的 Microsoft Entra 声明。 源系统（Microsoft Entra组成员身份、ADLS Gen2 ACL、Purview 标签分配或SharePoint ACL）中的权限更改仅在元数据通过特定于源的机制同步到索引后才会反映在搜索结果中，例如，后续索引器运行、推送 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），查询时的权限强制实施会使用文档中所述的源特定同步机制（索引器运行、推送 API 更新或 Purview 刷新）已写入索引的权限元数据。
  • 与查询后裁剪相比，可提升性能： 在搜索流程中进行筛选，比将更大的结果集加载到应用程序中再进行裁剪更快，尤其是在查询量较高时。
  • 重用现有标识基础结构： Microsoft Entra 和 SharePoint 标识仍然是访问决策的真相来源，从而减少标识重复和维护并行权限存储的操作开销。

教程和示例

使用更多文章和示例浏览Azure AI 搜索中的文档级访问控制。

相关内容

  • Last updated on