Use an Azure AI Search indexer to ingest Microsoft Purview sensitivity labels and enforce document-level security (preview)

Add Microsoft Purview sensitivity label support (preview) to an existing Azure AI Search indexer pipeline. Configure label extraction, annotate the target metadata fields, and map those values to each indexed document or chunk. Azure AI Search uses the indexed labels to enforce document-level access at query time according to your Microsoft Purview policies.

This functionality is available for the following data sources:

• Azure Blob Storage
• Azure Data Lake Storage Gen2
• SharePoint in Microsoft 365 (preview)
• Microsoft OneLake

The three-field examples in this article use metadata confirmed for SharePoint in Microsoft 365 document-library (drive) files. Sensitivity-label ingestion doesn't support SharePoint list items or site pages.

Prerequisites

• An existing data source and indexer configured by using the connector guidance linked in the previous section. If your pipeline indexes chunks, configure the skillset and index projections before adding label mappings.

• A target index created with purviewEnabled: true, or a plan to create a new Purview-enabled index and retarget the existing pipeline as described in Step 4.

• Configure Microsoft Purview sensitivity label policies and apply them to documents before indexing.

• Have the Global Administrator or Privileged Role Administrator roles in your Microsoft Entra tenant to grant the search service access to Purview APIs and sensitivity labels.

• Both the Azure AI Search service and the user issuing the query must be in the same Microsoft Entra tenant.

• Use source documents with file types that are both supported by Purview sensitivity labels and supported by Azure AI Search indexers.

• Use REST API version 2026-08-01-preview or an equivalent preview SDK package.

• The search service must use its system-assigned managed identity to authenticate with Microsoft Purview. This feature doesn't support user-assigned managed identities.

Limitations

• The Azure portal doesn't support this feature.

• Autocomplete and Suggest APIs aren't supported for Purview-enabled indexes, as they can't yet enforce label-based access control.

• Guest accounts and cross-tenant queries aren't supported.

• The following indexer features don't support documents with sensitivity labels. If you use any of these features in a skillset or indexer, documents with sensitivity labels aren't processed.

  • Custom Web API skill

  • Knowledge store, including the asset store required for image serving (preview) in agentic retrieval. Therefore, image serving isn't supported for knowledge sources that ingest sensitivity labels.

  • Indexer enrichment cache

  • Debug sessions

How policy enforcement works

Sensitivity label support has two phases: indexing and query-time enforcement.

Indexing

The indexer extracts document content and sensitivity-label metadata. On subsequent runs, it updates indexed values when it detects changes to a document's label, content, or metadata.

The index doesn't reflect label changes on source documents until the next successful indexer run.

Query-time enforcement

At query time, Azure AI Search evaluates sensitivity labels and enforces document-level access control based on the user's Microsoft Entra ID token and Microsoft Purview label policies. Only users authorized to access content with READ usage right under a given label can retrieve corresponding documents in search results.

For query authentication and authorization requirements, see Query a sensitivity labels-enabled index. For administrative investigations and audit behavior, see Elevated read.

1. Enable AI Search managed identity

Enable a system-assigned managed identity for your Azure AI Search service. The indexer uses the service's own identity to authenticate with Microsoft Purview and perform privileged EXTRACT operations, including reading encrypted content and security classifications. Assign the required roles directly to this identity in Step 3.

2. Enable RBAC on your AI Search service

Enable role-based access control (RBAC) on your Azure AI Search service. Purview-enabled indexes require RBAC authentication for document operations, including indexing content and querying. Keep both RBAC and API keys enabled if other service operations rely on API keys. This configuration doesn't permit API-key document operations on Purview-enabled indexes.

3. Grant access to extract sensitivity labels

Accessing Microsoft Purview sensitivity label metadata involves highly privileged operations. Engage your security or compliance teams and obtain approval through your organization's governance process before assigning permissions.

Once approved, engage a Global Administrator or Privileged Role Administrator to assign these roles to the Azure AI Search system-assigned managed identity:

• Content.SuperUser for label and content extraction.
• UnifiedPolicy.Tenant.Read for Purview policy and label metadata access.

Assign roles by using PowerShell

Assign these roles only to the system-assigned managed identity of the Azure AI Search service, not to a user-assigned managed identity, a separate application service principal, or an individual user account. The PowerShell script retrieves the managed identity object ID automatically from the service resource.

Your Global Administrator or Privileged Role Administrator should use the following PowerShell script to grant the required permissions. Obtain administrator consent for the delegated Microsoft Graph scopes AppRoleAssignment.ReadWrite.All and Application.Read.All through your approved governance process. A tenant administrator role alone doesn't supply these token scopes.

After installing the modules shown in the following section, establish a separate authenticated Azure PowerShell context in the same PowerShell session before running the remaining commands. Use Connect-AzAccount to sign in to the search service's tenant, and Set-AzContext to select the correct tenant and subscription. The Azure account must have permission to read the search service resource, such as the Reader role. Connect-Entra doesn't establish this Az context.

Replace the placeholders with your actual tenant ID, subscription ID, resource group, and search service name.

Install-Module -Name Az -Scope CurrentUser
Install-Module -Name Microsoft.Entra -AllowClobber
Import-Module Az.Resources
Connect-Entra -TenantId "<tenantId>" `
    -Scopes 'AppRoleAssignment.ReadWrite.All', 'Application.Read.All'

$resourceIdWithManagedIdentity = (
    "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/" +
    "providers/Microsoft.Search/searchServices/<searchServiceName>"
)
$managedIdentityObjectId = (Get-AzResource `
    -ResourceId $resourceIdWithManagedIdentity).Identity.PrincipalId

# Microsoft Information Protection (MIP)
$MIPResourceSP = Get-EntraServicePrincipal `
    -Filter "appID eq '870c4f2e-85b6-4d43-bdda-6ed9a579b725'"
New-EntraServicePrincipalAppRoleAssignment `
    -ServicePrincipalId $managedIdentityObjectId `
    -PrincipalId $managedIdentityObjectId `
    -ResourceId $MIPResourceSP.Id `
    -Id "8b2071cd-015a-4025-8052-1c0dba2d3f64"

# Microsoft Rights Management Services (MRMS) - policy read
$MRMSResourceSP = Get-EntraServicePrincipal `
    -Filter "appID eq '00000012-0000-0000-c000-000000000000'"
New-EntraServicePrincipalAppRoleAssignment `
    -ServicePrincipalId $managedIdentityObjectId `
    -PrincipalId $managedIdentityObjectId `
    -ResourceId $MRMSResourceSP.Id `
    -Id "7347eb49-7a1a-43c5-8eac-a5cd1d1c7cf0"

Reference: Connect-Entra, Get-AzResource, Get-EntraServicePrincipal, New-EntraServicePrincipalAppRoleAssignment, and Microsoft Graph app-role assignment permissions.

The script assigns application roles on the following resource service principals to the search service's managed identity:

4. Configure the index to enable Purview sensitivity label

Use REST API version 2026-08-01-preview for the configuration changes in the following steps.

For a Purview-enabled index, only RBAC authentication is supported for all document operations APIs. API-key access is limited to index schema retrieval (list and get).

Across all supported sensitivity-label data sources, metadata_sensitivity_label contains one label ID as a GUID string. Define its target index field as Edm.String, not a collection. The value can be absent or null when a document is unlabeled or label extraction is intentionally skipped.

Add these three string fields to the target index. If chunks are your searchable documents, add the fields to the chunk index.

The source_document_id field identifies the source document for auditing. It isn't the search index key or the projection parent key.

Index creation property: Include this property in a new index's full creation definition. If the existing index already has it, keep it unchanged.

{
  "purviewEnabled": true
}

Index field additions: Append these objects to the full index definition's fields array, preserving the existing schema and indexing layout.

[
  {
    "name": "sensitivity_label_id",
    "type": "Edm.String",
    "filterable": true,
    "retrievable": true,
    "sensitivityLabelId": true
  },
  {
    "name": "sensitivity_label_name",
    "type": "Edm.String",
    "retrievable": true,
    "sensitivityLabelName": true
  },
  {
    "name": "source_document_id",
    "type": "Edm.String",
    "retrievable": true,
    "sourceDocumentId": true
  }
]

Reference: Index definition.

For document-level mappings, follow Step 7. For child chunks, follow Step 6.

5. Configure the data source

Data source option delta: Add sensitivityLabel to indexerPermissionOptions in your configured data source. If other permission options are already enabled, retain them and append this option rather than replacing the array.

{
  "indexerPermissionOptions": ["sensitivityLabel"]
}

Reference: Data source definition.

This option enables label extraction. It's distinct from the sensitivityLabelId, sensitivityLabelName, and sourceDocumentId index field annotations. Keep the connector's existing credentials, container selection, and other settings.

6. Configure index projections in your skillset (if applicable)

If your pipeline indexes chunks, extend its existing index projection selector. Apply the field additions and Purview-enabled index requirement from Step 4 to the chunk index.

Projection mapping additions: Append these entries to the relevant selector's mappings array inside indexProjections.selectors. These additions aren't a complete selector or skillset.

[
  {
    "name": "sensitivity_label_id",
    "source": "/document/metadata_sensitivity_label"
  },
  {
    "name": "sensitivity_label_name",
    "source": "/document/metadata_sensitivity_label_name"
  },
  {
    "name": "source_document_id",
    "source": "/document/metadata_source_document_id"
  }
]

Reference: Skillset definition.

Preserve the selector's targetIndexName, parentKeyFieldName, and chunk sourceContext, except for retargeting a new index when required. Retain other selectors, content and vector mappings, and the existing projection mode. Explicitly map every non-key child field; the three additions above aren't the complete mapping set.

These root-level paths copy the mapped string values available on the parent onto every chunk. Projections generate the child key and parent association for change tracking. Don't manually map generated keys such as chunk_id or parent_id in projections or the chunked indexer's fieldMappings.

If your Text Split skill emits raw strings under chunks, use /document/chunks/* for the selector's sourceContext and content mapping, not an /id or /text child path.

With skipIndexingParentDocuments, direct indexer fieldMappings don't populate child documents. The label-ID projection is required for chunk-level query enforcement and associated label response metadata. For response handling, see Inspect sensitivity label metadata in the response.

For a two-index parent-child layout, use the direct mappings in Step 7 to populate the parent index and these projections to populate the child index. For mapping semantics, see Review field mappings.

7. Configure the indexer

For one search document per source document, add direct metadata mappings to your existing indexer. Use raw source field names without a /document/ prefix.

Direct field mapping additions: Append these entries to the indexer's fieldMappings array. Preserve its connector key mapping, other mappings, data source and skillset wiring, target index, and configuration, except for retargeting a new index when required.

[
  {
    "sourceFieldName": "metadata_sensitivity_label",
    "targetFieldName": "sensitivity_label_id"
  },
  {
    "sourceFieldName": "metadata_sensitivity_label_name",
    "targetFieldName": "sensitivity_label_name"
  },
  {
    "sourceFieldName": "metadata_source_document_id",
    "targetFieldName": "source_document_id"
  }
]

Reference: Indexer definition.

For chunks, keep the existing indexer connected to its skillset; the selector mappings in Step 6 populate child metadata.

Verify label ingestion

After merging the changes into the full resource definitions, perform an initial backfill if the existing indexer already processed the source files. Enabling extraction, adding metadata fields, or retargeting the pipeline doesn't make unchanged files eligible for a normal incremental run. To reprocess those files, reset the indexer, then run it. Reset clears change tracking and the subsequent run reprocesses all source documents; account for that workload.

If the files aren't indexed yet, run the indexer without reset. Use Get Indexer Status to confirm the execution completed successfully and inspect document errors and warnings. An accepted run request isn't proof of completed ingestion.

Using an authorized query identity and the query guide, verify a known labeled document and its chunks:

• A labeled file from any supported source populates sensitivity_label_id with a GUID string. For a labeled SharePoint document-library (drive) file, also verify the label name and source document audit ID in the companion fields; for other sources, verify companion values where that source metadata is available.
• An unlabeled document, or one with intentionally skipped label extraction, has an absent or null label ID.
• Every child chunk inherits the mapped metadata values available on its parent, and generated child and parent keys remain intact.

If expected metadata is missing, check the execution errors and warnings, the data source's extraction option in Step 5, and the direct or projection mappings in Steps 6 and 7. Confirm that the backfill processed the known file.

For later incremental refresh, run or schedule the indexer to process detected source changes; don't reset it for every label refresh. Source label changes aren't visible in the index until a successful indexer run processes them. For recurring refresh, see Schedule an indexer.

Related content

• How to query a sensitivity labels-enabled index
• Elevated read for administrative investigations
• Document-level security in Azure AI Search