Query-time enforcement of Microsoft Purview sensitivity labels in Azure AI Search (preview)

Note

Azure AI Search is available through the Azure portal, REST APIs, and Azure SDKs. It also underpins Foundry IQ, the managed knowledge layer that transforms enterprise content into reusable, permission-aware knowledge bases for agents in the Microsoft Foundry portal.

Important

These features and functionality are part of the 2026-05-01-preview REST API. The 2026-05-01-preview is licensed to you as part of your Azure subscription and is subject to the terms applicable to "Previews" in the Microsoft Product Terms, the Microsoft Products and Services Data Protection Addendum ("DPA"), and the Supplemental Terms of Use for Microsoft Azure Previews.

The 2026-05-01-preview supports connections to other Microsoft services and third-party services. Use of these services is subject to their respective terms and might result in data processing or storage outside of the Azure compliance boundary, as well as data flowing into the Azure compliance boundary.

The 2026-05-01-preview can't modify access permissions that were set outside of the 2026-05-01-preview. If you use the 2026-05-01-preview with access- or permission-restricted content, a timing lag occurs before the 2026-05-01-preview recognizes changes to those access or permission restrictions.

It's your responsibility to manage whether your data flows outside of your organization's compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries, and approvals are provisioned.

You're responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This responsibility includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. For more information, see the Azure AI Search Transparency Note.

At query time, Azure AI Search can enforce sensitivity label policies defined in Microsoft Purview. These policies include the evaluation of EXTRACT usage rights associated with each document, ensuring users can only retrieve documents they're permitted to access.

This capability extends document-level access control to align with your organization's information protection and compliance requirements managed in Microsoft Purview.

When Purview sensitivity label indexing is enabled, Azure AI Search checks each document's label metadata during query time. It applies access filters based on Purview policies to return only results the requesting user is allowed to access.

This article explains how query-time sensitivity label enforcement works and how to issue secure search queries.

Tip

If you consume labeled content through a knowledge base (retrieve action or MCP endpoint) instead of calling Azure AI Search directly, see Inspect sensitivity label metadata in retrieve responses for the equivalent response fields. Elevated read and Microsoft Purview audit logging documented in this article apply to both paths.

Prerequisites

Complete all steps in Use Azure AI Search indexers to ingest Microsoft Purview sensitivity labels.
Verify that the Azure AI Search service has its system-assigned managed identity (not a user-assigned managed identity) enabled and that it holds the Content.SuperUser and UnifiedPolicy.Tenant.Read role assignments. Query-time enforcement depends on label metadata that the indexer can extract only when the system-assigned identity has the correct configuration. See Step 1 in the indexer setup article.
Both the Azure AI Search service and the user issuing the query must be in the same Microsoft Entra tenant.
REST API version 2025-11-01-preview or an equivalent preview SDK package to query the index. The elevated read capability and Purview audit logging require 2026-05-01-preview or later.
Authenticate queries using Azure role-based access control (RBAC), not API keys. When Purview sensitivity labels are enabled, API key access is restricted to index schema retrieval.

Limitations

Guest accounts and cross-tenant queries aren't supported.
Autocomplete and Suggest APIs aren't supported for Purview-enabled indexes.
If label evaluation fails, the service returns a specific HTTP error code rather than a partial or unfiltered result set. For the complete list of error codes and causes, see Troubleshoot query errors.
The system evaluates labels only as they existed at the time of the last indexer run. Recent label changes might not be reflected until the next scheduled reindex.

How query-time sensitivity label enforcement works

When you query an index that includes Microsoft Purview sensitivity labels, Azure AI Search checks the associated Purview policies before returning results. In this way, the query returns only documents that the user token is allowed to access.

1. User identity and application role input

At query time, Azure AI Search validates both:

The calling application's RBAC role, provided in the Authorization header. The minimum required role is Search Index Data Reader. For more details, review the Azure AI Search RBAC guide.
The user identity via token, provided in the x-ms-query-source-authorization header.

Both are required to authorize label-based visibility.

Input type	Description	Example source
Application role	Determines whether the calling app has permission to execute queries on the index.	`Authorization: Bearer <app-token>`
User identity	Determines which sensitivity labels the end user is allowed to access.	`x-ms-query-source-authorization: <user-token>`

2. Sensitivity label evaluation

When a query request is received, Azure AI Search evaluates:

The sensitivityLabel field in each indexed document (extracted from Microsoft Purview during ingestion).
The user's effective Purview permissions, as defined by Microsoft Entra ID and Purview label policy.

If the user isn't authorized for a document's sensitivity label with EXTRACT permissions, that document is excluded from the query results.

Note

Internally, the service builds dynamic access filters similar to RBAC enforcement.
These filters aren't user-visible and can't be modified in the query payload.

3. Secure result filtering

Azure AI Search applies the security filter after all user-defined filters and scoring steps.
A document is included in the final result set only if:

The calling application has a valid role assignment (via RBAC), and
The user identity token represented by x-ms-query-source-authorization is valid and permitted to view content with the document's sensitivity label.

If either condition fails, the document is omitted from the results.

Acquire a user access token

To query Azure AI Search using user context, you must acquire an access token that represents the signed-in user. The approach you use depends on whether you're testing locally with your own token, if you have access to the source document, or implementing the application flow that requires passing the end-user token.

For testing scenarios

For local testing, you can retrieve a user access token using Azure CLI:

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

This approach uses your current Azure CLI login session, so you can use the context over documents you have EXTRACT permissions assigned via sensitivity labels. This method is intended for development and validation scenarios only.

Token acquisition for OBO scenarios

Applications that implement the on-behalf-of (OBO) flow must acquire tokens through Microsoft Entra ID by using a supported authentication library, such as the Microsoft Authentication Library (MSAL).

In OBO scenarios, request the token for the downstream API that the application calls. For example, when calling Azure AI Search, the resource URI is https://search.azure.com/.default.

The .default scope requests all delegated permissions that the application preconsented for the specified resource.

Sensitivity label permissions, including EXTRACT, aren't represented as OAuth scopes. The downstream service, such as Azure AI Search, evaluates these permissions at runtime based on the user identity in the token and the applied sensitivity label policy.

Query example

Here's an example of a query request that uses Microsoft Purview sensitivity label enforcement.

Pass the application token as a bearer token in the Authorization header. Pass the user token as the raw token value in the x-ms-query-source-authorization header, without the Bearer prefix.

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2025-11-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"
}

Elevated read for administrative investigations (preview)

Elevated read lets an authorized developer return labeled documents that the calling user normally can't see, while emitting a Microsoft Purview audit log entry for every document the request returns. Use it for compliance reviews, eDiscovery, incident response, and other administrative investigations where an auditable record of access is required.

Elevated read is available on Purview-enabled indexes in REST API version 2026-05-01-preview and later.

How elevated read works

The calling application sets the x-ms-enable-elevated-read: true header on the search request.
Azure AI Search skips the per-document label-based access check and returns matching documents, regardless of the requesting user's EXTRACT permissions on each label.
For each document in the response, Azure AI Search emits one entry to the Microsoft Purview audit log on behalf of the requesting tenant. A single search request that returns N documents produces N audit entries.
Audit entries are uploaded to Purview asynchronously after the search response is returned.

Required role assignment

The calling developer user must hold the Search Index Data Contributor role on the search service or index scope. Search Index Data Reader isn't sufficient. Elevated read fails with 403 Forbidden if the role isn't assigned. For more information about Azure AI Search roles, see Connect to Azure AI Search using roles.

When the x-ms-enable-elevated-read header is set to true, the x-ms-query-source-authorization header isn't allowed to be used.

Elevated read example

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

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

Audit fields sent to Microsoft Purview

Each audit entry follows the Office 365 management activity API schema and includes the following fields.

Category	Field	Description
Standard schema	`CreationTime`	UTC timestamp of the elevated read request.
Standard schema	`Operation`	The operation name that identifies the elevated read action.
Standard schema	`OrganizationId`	The Microsoft Entra tenant ID of the search service.
Standard schema	`RecordType`	The Office 365 management activity record type for Azure AI Search.
Standard schema	`UserType`	The type of user that issued the request.
Standard schema	`UserId`	The unique identifier (PUID) of the requesting user.
Standard schema	`UserPrincipalName`	The user principal name (UPN) of the requesting user.
Standard schema	`ClientIP`	The IP address of the calling application.
Azure AI Search	`UserObjectId`	The Microsoft Entra object ID of the requesting user.
Azure AI Search	`DocumentDataSourceType`	The type of source for the accessed document, such as `azureblob`, `sharepoint`, `onelake`, or `searchIndex`.
Azure AI Search	`DocumentDataSourceId`	The source-specific identifier of the accessed document, such as the blob URL or SharePoint item ID.
Azure AI Search	`SensitivityLabelName`	The display name of the sensitivity label applied to the accessed document.

Graceful degradation

If Azure AI Search can't reach Microsoft Purview while processing a query, such as during a transient Purview outage, it skips label evaluation for that request. The behavior depends on whether the request includes a user identity token:

Elevated read requests (x-ms-enable-elevated-read: true): The request fails with 5xx. Azure AI Search doesn't return labeled documents without first being able to emit audit logs.
Standard label-enforced requests (with x-ms-query-source-authorization): The request fails with 5xx. Azure AI Search doesn't return partial or unfiltered results when it can't evaluate label policies.
Calls without x-ms-query-source-authorization issued by an application with at least the Search Index Data Reader role: The request succeeds and returns only documents that don't have a sensitivity label. Labeled documents are omitted from the response.

This degraded path is intended only for non-user-facing workflows that explicitly accept unlabeled-only results. Don't rely on it for end-user search experiences.

For the complete list of error codes returned during query-time sensitivity label evaluation, see Troubleshoot query errors.

Find elevated read audit logs in Microsoft Purview

Azure AI Search uploads audit entries to the calling tenant's Microsoft Purview audit log. To investigate elevated read activity:

In the Microsoft Purview portal, select Solutions > Audit.
Select Audit Search, and then filter by date range, user, or the Azure AI Search record type.
Open an entry to view the standard schema fields and the Azure AI Search custom fields, including SensitivityLabelName, DocumentDataSourceType, and DocumentDataSourceId.

For step-by-step guidance on running audit searches, retention behavior, and required Purview roles, see Search the audit log in the Microsoft Purview portal.

Sensitivity label handling in Azure AI Search

When Azure AI Search indexes document content with sensitivity labels from sources like SharePoint, Azure Blob, and others, it stores both the content and the label metadata. The search query returns indexed content along with the GUID that identifies the sensitivity label applied to the document, only if the user has data EXTRACT access for that document assigned via the sensitivity label definition. This GUID uniquely identifies the label but doesn't include human-readable properties such as the label name or associated permissions.

Note that the GUID alone is insufficient for scenarios that include user interface because sensitivity labels often carry other policy controls enforced by Microsoft Purview Information Protection, such as: print permissions or screenshot and screen capture restrictions. Azure AI Search doesn't surface these capabilities.

To display label names and/or enforce UI-specific restrictions, your application must call the Microsoft Purview Information Protection endpoint to retrieve full label metadata and associated permissions.

You can use the GUID returned by Azure AI Search to resolve the label properties and call the Purview Labels APIs to fetch the label name, description, and policy settings.

Troubleshoot query errors

When query-time sensitivity label evaluation fails, Azure AI Search returns a specific HTTP error code that identifies the cause. The service never returns a partial or unfiltered result set. If label policies can't be evaluated, the query fails rather than exposing unlabeled or unauthorized content.

400 Bad Request

A 400 error indicates a problem with the index configuration or the request headers. Fix the configuration before retrying.

Condition	What to check
The index defines both a new sensitivity label field and one or more legacy `permissionFilter: sensitivityLabel` fields.	Use only one configuration style. Remove either the new sensitivity label field or all legacy permission-filter fields from the index schema. See configure the index for guidance.
The index defines more than one legacy `permissionFilter: sensitivityLabel` field.	An index supports exactly one legacy permission-filter field for sensitivity labels. Remove the duplicate fields from the index schema.
The index is configured for Purview filtering but has no sensitivity label field defined.	Add the required sensitivity label field to the index schema. See configure the index.
The delegated user email is invalid, or the user isn't in the same Microsoft Entra tenant as the Azure AI Search service.	Verify that the token in `x-ms-query-source-authorization` belongs to a user in the same tenant as the search service. Cross-tenant queries aren't supported.
Microsoft Purview rejected the request because the `x-ms-query-source-authorization` header is absent, malformed, or the tenant isn't onboarded to Microsoft Purview Information Protection.	Check that the `x-ms-query-source-authorization` header is present and contains a valid delegated user token. Confirm that the tenant is onboarded to Microsoft Purview Information Protection.

401 Unauthorized

A 401 error indicates a problem with the authorization token or the application's Purview permissions.

Condition	What to check
The `Authorization: Bearer` token has no tenant ID claim, or is an app-only token without a delegated user context.	Use a delegated token that includes a tenant ID claim. App-only tokens aren't supported for label-enforced queries.
The `Authorization` header is absent or doesn't use the `Bearer` scheme.	Add an `Authorization: Bearer <token>` header to the request.
The delegated token is invalid or expired, admin consent for the required Purview scopes is missing, or the tenant blocks token exchange for Purview.	Reacquire the token. If the error persists, verify that an administrator has granted admin consent for the required Microsoft Purview API permissions for the calling application in Microsoft Entra ID.
The token endpoint succeeded but returned no access token.	Check the application's permission configuration in Microsoft Entra ID. Make sure the application has the required delegated Purview permissions and that admin consent is in place.
The calling user hasn't consented to the required Purview API permissions, or doesn't have access to Microsoft Purview Information Protection in the tenant.	Make sure the user has the required Purview permissions assigned. Contact your Microsoft Purview or Microsoft Entra administrator to verify the user's access.

502 Bad Gateway

A 502 error indicates a connectivity failure between Azure AI Search and Microsoft Purview. These errors are typically transient.

Condition	What to check
A network or connectivity failure occurred when Azure AI Search contacted Microsoft Purview.	Retry the query. If the error persists, check Health > Service health in the Microsoft 365 admin center to confirm Microsoft Purview Information Protection has no active incidents.
An unexpected error occurred during Purview communication.	Retry the query. If the error persists, contact Microsoft Support. If the response includes a correlation ID, provide it when filing a support request.

504 Gateway Timeout

A 504 error indicates that Microsoft Purview didn't respond within the allowed time.

Condition	What to check
Microsoft Purview didn't respond within the allowed time.	Retry the query — this error is often transient. If the issue persists, check Health > Service health in the Microsoft 365 admin center to confirm Microsoft Purview Information Protection has no active incidents.

End-to-end testing setup

To help you validate your sensitivity label configuration in Azure AI Search, see the reference end-to-end setup.

This repository demonstrates how to:

Configure sensitivity labels sync and honoring in Azure AI Search
Test ingestion and query-time enforcement scenarios for documents with sensitivity labels
Extract the label name and expose it as part of the citations used in your RAG applications or agents.

Feedback

Was this page helpful?

Last updated on 2026-07-08