Azure AI 搜索 中 Microsoft Purview 敏感度标签在查询时的强制执行（预览版）

在查询时，Azure AI 搜索 可以强制执行在 Microsoft Purview 中定义的敏感度标签策略（预览）。 这些策略包括评估EXTRACT与每个文档关联的使用权限，确保用户只能检索他们有权访问的文档。

此功能扩展了 文档级别访问控制，以符合组织在 Microsoft Purview 内管理的 信息保护和合规性要求。

启用 Purview 敏感度标签索引后，Azure AI 搜索在查询期间检查每个文档的标签元数据。 它基于 Purview 策略应用访问筛选器，以仅返回请求用户有权访问的结果。

本文介绍查询时敏感度标签强制实施的工作原理，以及如何发出安全搜索查询。

先决条件

• 完成使用 Azure AI 搜索 索引器引入 Microsoft Purview 敏感度标签这篇文章中的所有步骤。

• 验证Azure AI 搜索服务是否已启用系统分配的托管标识（而不是用户分配的托管标识），以及它是否具有角色Content.SuperUserUnifiedPolicy.Tenant.Read分配。 查询时强制实施依赖于标签元数据，而索引器只有在系统分配的标识已正确配置时才能提取这些元数据。 请参阅索引器设置文章中的 步骤 1 。

• Azure AI 搜索服务和发出查询的用户必须位于同一Microsoft Entra租户中。

• 使用 REST API 版本 2025-11-01-preview 或更高版本，或等效的预览版 SDK 包来查询索引。 提升读取功能和 Purview 审计日志需要使用 2026-05-01-preview 或更高版本。

• 使用 Azure 基于角色的访问控制（RBAC）而不是 API 密钥对查询进行身份验证。 启用 Purview 敏感度标签后，API 密钥访问仅限于索引架构检索。

限制

• 不支持来宾帐户和跨租户查询。

• 已启用 Purview 的索引不支持自动完成和建议 API。

• 如果标签评估失败，服务将返回特定的 HTTP 错误代码，而不是部分或未筛选的结果集。 有关错误代码和原因的完整列表，请参阅 “排查查询错误”。

• 系统仅根据标签在上次索引器运行时的状态进行评估。 在下次计划的重新编制索引之前，可能不会反映最近的标签更改。

查询时敏感度标签强制执行的工作原理

查询包含Microsoft Purview敏感度标签的索引时，Azure AI 搜索在返回结果之前检查关联的 Purview 策略。 这样，查询仅返回用户令牌有权限访问的文档。

1.用户标识和应用程序角色输入

在查询时，Azure AI 搜索验证两者：

• 调用应用程序的 RBAC 角色，在 Authorization 标头中提供。 所需的最低角色为 Search Index Data Reader。 有关更多详细信息，请查看 Azure AI 搜索 RBAC 指南。
• x-ms-query-source-authorization 标头中提供的使用令牌的用户标识。

需要这两项才能授权基于标签的可见性。

2. 敏感度标签评估

收到查询请求后，Azure AI 搜索计算结果：

1. 每个索引文档中的 sensitivityLabel 字段（在引入过程期间从 Microsoft Purview 提取）。
2. 用户的有效 Purview 权限，由 Microsoft Entra ID 和 Purview 标签策略定义。

如果用户没有获得具有 EXTRACT 权限的文档敏感度标签的授权，该文档将从查询结果中排除。

3.保护结果筛选

Azure AI 搜索在所有用户定义筛选器和评分步骤之后应用安全筛选器。
只有在以下条件下，文档才会包含在最终结果集中：

• 调用应用程序具有有效的角色分配（通过 RBAC），并且
• 表示 x-ms-query-source-authorization 的用户标识令牌有效，并允许使用文档的敏感度标签查看内容。

如果任一条件失败，则会从结果中省略文档。

获取用户访问令牌

若要使用用户上下文查询Azure AI 搜索，必须获取表示已登录用户的访问令牌。 使用的方法取决于是使用自己的令牌在本地进行测试，还是有权访问源文档，还是实现需要传递最终用户令牌的应用程序流。

适用于测试应用场景

对于本地测试，可以使用Azure CLI检索用户访问令牌：

$token = az account get-access-token `
  --resource https://search.azure.com `
  --query accessToken `
  --output tsv

此方法依赖于您当前的 Azure CLI 登录会话，因此，您可以在通过敏感度标签分配有EXTRACT权限的文档上使用该上下文。 此方法仅适用于开发和验证方案。

适用于 OBO 应用场景的令牌获取

实现代理 (OBO) 流的应用程序必须通过受支持的身份验证库（例如 Microsoft 身份验证库 (MSAL)）使用 Microsoft Entra ID 获取令牌。

在 OBO 方案中，请求应用程序调用的下游 API 的令牌。 例如，调用Azure AI 搜索时，资源 URI 为 https://search.azure.com/.default。

.default 作用域请求应用程序为指定资源预先同意的所有委派权限。

敏感度标签权限（包括 EXTRACT）不表示为 OAuth 范围。 下游服务（例如Azure AI 搜索）根据令牌中的用户标识和应用的敏感度标签策略在运行时评估这些权限。

查询示例

下面是使用Microsoft Purview敏感度标签强制的查询请求的示例。

在 Authorization 标头中传递应用程序令牌作为持有者令牌。 将用户令牌作为标头中的 x-ms-query-source-authorization 原始令牌值传递，而不使用 Bearer 前缀。

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

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

用于管理调查的提升读取权限（预览）

提升读取权限允许获得授权的开发人员返回调用用户通常无权查看的带标签的文档，同时针对请求返回的每个文档生成一条 Microsoft Purview 审核日志记录。 将其用于合规性评审、电子数据展示、事件响应和其他管理调查，其中需要可审核的访问权限记录。

在 REST API 版本 2026-05-01-preview 及更高版本中，提升读取可用于启用了 Purview 的索引。

提升读取的工作原理

1. 调用应用程序在 x-ms-enable-elevated-read: true 搜索请求上设置标头。

2. Azure AI 搜索跳过基于每个文档标签的访问检查并返回匹配的文档，而不考虑请求用户的EXTRACT每个标签的权限。

3. 对于响应中的每个文档，Azure AI 搜索代表请求租户向 Microsoft Purview 审核日志发出一个条目。 返回 N 文档的单个搜索请求生成 N 个审核条目。

4. 返回搜索响应后，审核条目将异步上传到 Purview。

所需的角色分配

调用开发人员用户必须在搜索服务或索引范围上保留搜索索引数据参与者角色。 搜索索引数据读取者是不够的。 如果未分配该角色，则提升读取失败，返回 403 Forbidden。 有关 Azure AI 搜索 角色的详细信息，请参阅 使用角色连接到 Azure AI 搜索。

当 x-ms-enable-elevated-read 标头设置为 true 时，不允许使用 x-ms-query-source-authorization 标头。

提升读取示例

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{contributor-token}}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

发送到 Microsoft Purview 的审计字段

每个审核条目都遵循 Office 365 管理活动 API 架构，并包含以下字段。

平稳降级

如果在处理查询时（例如在暂时性 Purview 中断期间），Azure AI 搜索无法访问Microsoft Purview，则会跳过该请求的标签评估。 此行为取决于请求是否包括用户标识令牌：

• 高权限读取请求 (x-ms-enable-elevated-read: true)：该请求因 5xx 而失败。 Azure AI 搜索 在未先能够输出审计日志之前，无法返回带有标签的文档。

• 标准标签强制请求 （with x-ms-query-source-authorization）： 请求失败并出现 5xx。 当无法评估标签策略时，Azure AI 搜索不会返回部分或未筛选的结果。

• 未包含 x-ms-query-source-authorization 的调用（由至少具有 搜索索引数据读取器 角色的应用发出）：请求会成功，并且仅返回未带有敏感度标签的文档。 标记的文档将从响应中省略。

此降级路径仅适用于明确接受仅含未标记结果的非面向用户的工作流。 不要依赖它来获得最终用户搜索体验。

有关在查询时间敏感度标签评估期间返回的错误代码的完整列表，请参阅 “排查查询错误”。

在 Microsoft Purview 中查找提升读取审计日志

Azure AI 搜索将审核条目上传到调用租户的Microsoft Purview审核日志。 若要调查提升读取活动，请执行以下操作：

1. 在 Microsoft Purview 门户 中，选择 Solutions>Audit。

2. 选择 Audit Search，然后按日期范围、用户或Azure AI 搜索记录类型进行筛选。

3. 打开一个条目以查看标准架构字段和Azure AI 搜索自定义字段，包括 SensitivityLabelName、DocumentDataSourceType 和 DocumentDataSourceId。

有关执行审核搜索、保留行为和所需 Purview 角色的分步指导，请参阅在 Microsoft Purview 门户中搜索审核日志。

Azure AI 搜索中的敏感度标签处理

当Azure AI 搜索索引来自源（如 SharePoint、Azure Blob 等）的敏感度标签的文档内容时，它将存储内容和标签元数据。 仅当用户具有通过敏感度标签定义分配的文档的数据 EXTRACT 访问权限时，搜索查询才会返回索引内容以及标识应用于文档的敏感度标签的 GUID。 此 GUID 唯一标识标签，但不包括可读属性，例如标签名称或关联权限。

请注意，仅 GUID 不能满足包含用户界面的情境需求，因为敏感度标签通常包含由 Microsoft Purview 信息保护 强制实施的其他策略控制，例如：打印权限或屏幕截图和捕获限制。 Azure AI 搜索不会呈现这些功能。

若要显示标签名称和/或强制实施特定于 UI 的限制，应用程序必须调用Microsoft Purview 信息保护终结点来检索完整的标签元数据和关联权限。

可以使用Azure AI 搜索返回的 GUID 解析标签属性，并调用 Purview 标签 API提取标签名称、说明和策略设置。

排查查询错误

当查询时敏感度标签评估失败时，Azure AI 搜索返回标识原因的特定 HTTP 错误代码。 服务永远不会返回部分或未筛选的结果集。 如果无法评估标签策略，查询将失败，而不是公开未标记或未经授权的内容。

400 错误的请求

400 错误指示索引配置或请求标头出现问题。 在重试之前修复配置。

401 未授权

401 错误指示授权令牌或应用程序的 Purview 权限出现问题。

502 错误的网关

502 错误表示Azure AI 搜索与Microsoft Purview之间的连接失败。 这些错误通常是暂时性的。

504 网关超时

504 错误表示Microsoft Purview在允许的时间内未响应。

端到端测试设置

若要帮助你验证Azure AI 搜索中的敏感度标签配置，请参阅参考端到端设置。

此存储库演示如何：

• 配置敏感度标签同步和在 Azure AI 搜索中的遵守
• 针对带有敏感度标签的文档测试引入和查询时强制执行场景
• 提取标签名称，并将其作为 RAG 应用程序或代理中所用引用的一部分对外提供。