Document-level access control in Foundry IQ (Azure AI Search)

Note

Foundry IQ (Azure AI Search) provides direct indexing and query APIs alongside higher-level knowledge source and knowledge base APIs for managed retrieval. Use the Azure portal, REST APIs, or Azure SDKs to configure these capabilities, or connect agents to knowledge bases in the Microsoft Foundry portal.

Important

Features or capabilities marked (preview) in this article are in Public Preview and are subject to the Supplemental Terms of Use for Microsoft Azure Previews.

For preview terms specific to Foundry IQ (Azure AI Search), see Preview functionality.

SharePoint ACL ingestion and query-time permission filtering, ADLS Gen2 ACL/RBAC, and standard Blob container RBAC are generally available with the 2026-10-01 data plane REST API. Push ACL ingestion is also generally available. Microsoft Purview sensitivity label enforcement remains in preview.

Foundry IQ (Azure AI Search) supports document-level access control, enabling organizations to enforce fine-grained permissions at the document level, from data ingestion through query execution. This capability is essential for building secure AI agentic systems grounding data, retrieval-augmented generation (RAG) applications, and enterprise search solutions that require authorization checks at the document level.

Approaches for document-level access control

Foundry IQ provides five primary approaches to enforce document-level permissions, each suited to different data sources and identity models.

Approach Description
Security filters String comparison. Your application passes in a user or group identity as a string, which populates a filter on a query, excluding any documents that don't match on the string.

Security filters are a technique for achieving document-level access control. This approach isn't bound to an API so you can use any version or package.
POSIX-like ACL / RBAC scopes The delegated user's Microsoft Entra identity is evaluated against supported permission metadata. ADLS Gen2 ACL and container RBAC scope ingestion, standard Blob container RBAC scope ingestion, and their query permission filtering are generally available in REST API 2026-10-01. Customer-managed push ACL ingestion is also generally available. Other features retain their documented availability; not all Storage authorization policies are supported. For API and SDK guidance, see Retrieve ACL permissions metadata.
Microsoft Purview sensitivity labels (preview) Indexer extracts sensitivity labels defined in Microsoft Purview from supported data sources (Azure Blob Storage, ADLS Gen2, SharePoint in Microsoft 365, OneLake). These labels are stored as metadata and evaluated at query time to enforce user access based on Microsoft Entra tokens and Purview policy assignments. Labels are also surfaced through knowledge sources and the agentic retrieval response, allowing AI agents and chat apps consuming a knowledge base to receive the same label-aware filtering. This approach aligns Foundry IQ authorization with your enterprise's Microsoft Information Protection model.
SharePoint in Microsoft 365 ACLs Foundry IQ indexers extract supported permission metadata and use it for query-time access checks with REST API 2026-10-01. For the indexed permission subset, group limits, synchronization behavior, and configuration, see Use a SharePoint indexer to ingest permission metadata.
OneLake source permissions (preview) Uses indexed source locations and query-time OneLake authorization rather than copied user and group ACLs. See Preserve OneLake permissions.

For indexed knowledge sources, ingestionPermissionOptions can't be combined with assetStore. Therefore, image serving (preview) isn't available when native document-level permission ingestion is enabled.

Supported parsing and content extraction for permission ingestion

When you enable native document-level permissions for SharePoint, ADLS Gen2, or Blob Storage, use standard or default document parsing and content extraction. Preserve each source item's permission metadata and source context throughout ingestion.

You can also use Content Understanding-based extraction, where supported by your data source and API. Configure every generated chunk to retain the required permission metadata and source context. Supported downstream chunking isn't the same as selecting a specialized source parsing mode.

For REST API 2026-10-01, use the settings for the resource you configure:

Resource REST property Configuration
SharePoint, ADLS Gen2, or Blob indexer parameters.configuration.parsingMode Use default for standard document parsing.
Blob knowledge source, including ADLS Gen2 azureBlobParameters.ingestionParameters.contentExtractionMode minimal is the default extraction option; standard selects Content Understanding-based extraction. Preserve the generated permission and source-context mappings.
Indexed SharePoint knowledge source indexedSharePointParameters.ingestionParameters.contentExtractionMode minimal is the default extraction option; use standard for Content Understanding-based extraction where supported. Configure extraction through the knowledge-source API, not by changing generated parser settings.

Knowledge-source contentExtractionMode and indexer parsingMode are different settings. In particular, minimal isn't a specialized plain-text parsing mode. For the REST definitions, see Indexers - Create and Knowledge Sources - Create or Update.

Other customer-selected parsing modes aren't supported with document-level permissions at this time. Don't select:

  • JSON parsing (json).
  • JSON array parsing (jsonArray) or parsing multiple JSON documents into separate records.
  • JSON Lines parsing (jsonLines).
  • CSV or delimited-text parsing (delimitedText).
  • Plain-text-specific parsing (text).
  • Markdown-specific parsing (markdown).
  • Any other mode that creates, splits, reshapes, or maps multiple logical records from one source item without a supported permission-propagation contract.

These restrictions concern parsing modes, not file extensions or the format of extracted content. For example, a plain-text file processed with default parsing doesn't use the specialized text mode. Markdown output from Content Understanding isn't the markdown source parsing mode.

For chunk mappings and required source metadata, see the SharePoint permission guidance, ADLS Gen2 permission guidance, and Blob RBAC scope guidance.

Trust the source of indexed permissions

Query-time permission filtering evaluates the permission metadata associated with an indexed record. Separately, your ingestion design must establish who is authorized to choose that record's identity and grant access to its content. A document key selects a record for updates or merges; it isn't an authorization boundary.

For native connector ingestion, follow the source-specific configuration and preserve the association between source content, identity, and connector-derived permissions. For customer-managed push ingestion, the authorized publisher supplies the key and permission values. Application-managed string filtering also depends on the application's authentication and filter construction.

Don't treat ordinary lower-trust content as authorized permission metadata merely because a field name matches. Review source writers, ingestion administrators, implicit and explicit mappings, enrichment outputs, and projected children. For Blob ingestion, use the identity and permission configuration checklist. This review is separate from permission freshness.

Choose an approach

Use the following criteria to identify the approach that best fits your data source, identity model, and compliance requirements.

Scenario Recommended approach Why
Custom identity system or non-Microsoft security framework. Security filters API-agnostic, generally available, and based on simple string matching.
Microsoft Entra user and group permissions pushed to an index, indexed ADLS Gen2 ACLs, or indexed container RBAC scopes from ADLS Gen2 and Azure Blob Storage. POSIX-like ACL / RBAC scopes Uses native permission metadata for query-time enforcement. The schema, push indexing, and query enforcement are generally available in REST API 2026-10-01; source-specific ingestion has separate availability requirements.
Enterprise content already governed by Microsoft Purview information protection policies. Microsoft Purview sensitivity labels Reuses centralized classification and policy assignments across Foundry IQ.
Content sourced from SharePoint in Microsoft 365 (libraries, lists, ASPX site pages). SharePoint in Microsoft 365 ACLs Evaluates the supported permission subset synchronized into Search. For source-side request-time retrieval or customer-controlled update submission, compare SharePoint retrieval approaches and freshness.

Pattern for security trimming using filters

For scenarios where native ACL/RBAC scopes integration isn't viable, use security string filters to trim results based on exclusion criteria. The pattern includes the following components:

  • To store user or group identities, create a string field in the index.
  • Load the index using source documents that include associated ACLs.
  • Include a filter expression in your query logic for matching on the string.
  • At query time, get the identity of the caller.
  • Pass in the identity of the caller as the filter string.
  • Results are trimmed to exclude any matches that fail to include the user or group identity string.

You can use push or pull model APIs. Because this approach is API agnostic, you just need to confirm that the index and query have valid strings (identities) for the filtration step.

This approach is useful for systems with custom access models or non-Microsoft security frameworks. For more information about this approach, see Security filters for trimming results in Foundry IQ.

Pattern for native support for POSIX-like ACL and RBAC scope permissions

Native permission filtering uses indexed Microsoft Entra user and group object IDs and storage container RBAC scopes.

Azure Data Lake Storage (ADLS) Gen2 supports ACLs on directories and files. Use an ADLS Gen2 indexer or a Blob knowledge source configured for ADLS Gen2 to ingest supported ACLs and container RBAC scopes with REST API 2026-10-01. For standard Blob Storage, the Blob indexer or knowledge source ingests container RBAC scopes, not per-file ACLs.

For ACL-secured content, use group access over individual user access for ease of management. The pattern includes the following components:

Native permission-filtered queries distinguish the caller from the user whose document permissions are evaluated:

  • Authorization carries the caller's token for Search RBAC. An application service principal or managed identity can call Search with the appropriate role, such as Search Index Data Reader or Search Index Data Contributor.
  • x-ms-query-source-authorization carries a delegated user's token for document-permission evaluation. Groups are permission metadata, not token-bearing identities.

An application that can call Search isn't necessarily supported as a document-permission subject. For example, an authorized application can use elevated read on a non-Purview index, but that administrative bypass doesn't evaluate application ACL membership. For supported token flows and operation-specific limits, see Application-token boundaries.

Use the push API workflow to load content and native permission metadata.

Use the pull model (indexer) APIs for ADLS Gen2 ACLs and container scopes, or standard Blob container scopes, with REST API 2026-10-01.

Retrieve ACL permissions metadata during ingestion

How you retrieve ACL permissions varies depending on whether you're pushing a documents payload or using the ADLS Gen2 indexer.

For ADLS Gen2 and standard Blob permission ingestion, use REST API 2026-10-01. Check SDK changelogs for support of that API and the required properties. GA REST availability doesn't establish SDK package readiness.

Push ACL ingestion is generally available. The push guide includes a 2026-10-01 REST workflow. Check SDK changelogs for support of permission filters and ACL/RBAC ingestion:

For the push model approach:

  1. Create an index schema with permission filters by using the REST API or an Azure SDK package that supports the required properties.
  2. Consider using the Microsoft Graph SDK to get group or user identities.
  3. Use the Index Documents or equivalent Azure SDK API to push documents and their associated permission metadata into the search index.

For the pull model ADLS Gen2 indexer approach or Blob (ADLS Gen2) knowledge source:

  1. Verify that files in the directory are secured using the ADLS Gen2 access control model.
  2. Use Indexers - Create (REST API), Knowledge Sources - Create (REST API), or an equivalent Azure SDK API to create the indexer, index, and data source.

If your skillset chunks ADLS or Blob documents, populate permissions on every protected chunk through index projections, not only indexer field mappings.

Source metadata for permission ingestion

Source context and permission grants serve different purposes. Preserve source paths as raw values, not encoded keys, citation URLs, or generated parent IDs.

Source and scenario Source metadata and purpose Mapping and availability
ADLS named-user/group ACLs Required metadata_storage_path (Edm.String) identifies the source. metadata_user_ids and metadata_group_ids contain effective ACLs. Map ACLs to Collection(Edm.String) fields annotated userIds and groupIds. Preserve the path on records and chunks. GA in 2026-10-01.
ADLS RBAC-only metadata_storage_path is required for ADLS permission ingestion, even without ACL fields. metadata_rbac_scope identifies the container. Map the scope to an Edm.String field annotated rbacScope. The required path isn't used to copy role assignments. GA in 2026-10-01.
ADLS mixed ACL/RBAC Source path, effective user/group ACLs, and container scope. Preserve all configured fields on records and projected chunks. Any independent supported grant can authorize access. GA in 2026-10-01.
Standard Blob RBAC metadata_rbac_scope identifies the container; a per-document path isn't required to calculate this scope. Generated knowledge-source pipelines still include metadata_storage_path. Map the scalar scope to an rbacScope-annotated field on documents and chunks. No ADLS file ACL inference. GA in 2026-10-01.
SharePoint ACLs metadata_spo_item_path provides item context; metadata_spo_site_url provides site context. Lists and pages also use metadata_spo_site_asset_item_id. Use the source-specific SharePoint schema and projection guidance. SharePoint availability and requirements are independent of the Storage GA scope.

For direct schema definitions, authoritative mappings, generated pipelines, and existing-record remediation, see ADLS permission ingestion and Blob RBAC scope ingestion.

For ADLS source ACLs that grant broad access while excluding named identities, see Unsupported implicit blocklists.

Pattern for SharePoint in Microsoft 365 basic ACL permissions ingestion

For indexed SharePoint content, Foundry IQ can store supported source permissions as metadata and use them to filter query results. Use the SharePoint in Microsoft 365 indexer with REST API 2026-10-01 for this permission configuration, or an SDK package that supports the feature.

For permission requirements, supported group relationships, permission synchronization, and limitations, see Use a SharePoint indexer to ingest permission metadata.

If your skillset chunks documents (for example, with the Text Split skill for integrated vectorization), the ACL fields move from indexer field mappings to index projections. See Choose where to populate ACL fields.

Pattern for Microsoft Purview sensitivity labels (preview)

When you enable label ingestion, Foundry IQ extracts sensitivity metadata from supported data sources. These data sources include Azure Blob Storage, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint in Microsoft 365, and Microsoft OneLake. The extracted labels are stored in the index alongside document content.

At query time, Foundry IQ checks each document's sensitivity label, the user's Microsoft Entra token, and the organization's Purview policies to determine access. The system returns documents only if the user's identity and label-based permissions allow access under the configured Purview policies.

This pattern includes the following components:

  • Configure your index, data source, and indexer (for scheduling purposes) by using REST API 2026-11-01-preview or a preview SDK that supports Purview label ingestion.
  • Enable a system-assigned managed identity on your Foundry IQ service. User-assigned managed identities aren't supported for Purview label extraction - the service's own identity must hold the elevated Purview permissions. Then have your tenant global administrator or privileged role administrator grant the required access to allow the Foundry IQ service to authenticate with Microsoft Purview and extract label metadata.
  • Apply sensitivity labels to documents before indexing so the system can recognize and preserve them during ingestion.
  • At query time, attach a valid Microsoft Entra token via the header x-ms-query-source-authorization to each query request. Foundry IQ evaluates the token and the associated label metadata to enforce label-based access control.

Purview sensitivity label enforcement is limited to single-tenant scenarios and requires RBAC authentication. During the preview, it's supported only through the REST API and Azure SDKs. Autocomplete and Suggest APIs aren't currently available for Purview-enabled indexes.

Where sensitivity labels are surfaced

Before the system can enforce labels at query time or return them in retrieve responses, you must first synchronize the label metadata into the index. Both consumption paths described in this section depend on this synchronization step. You can synchronize labels either by configuring a Foundry IQ indexer directly against a supported data source, or by enabling the equivalent ingestion option when you create a knowledge source. In both cases, your environment must meet the sensitivity label metadata sync configuration prerequisites (managed identity, RBAC on the Foundry IQ service, and the required Microsoft Purview and data-source permissions). For end-to-end indexer setup, see Use Foundry IQ indexers to ingest Microsoft Purview sensitivity labels. For knowledge-source-driven ingestion, set ingestionPermissionOptions to include sensitivityLabel during knowledge source creation.

After you synchronize labels, two query paths consume the same indexed label metadata. Choose the path that matches how your application calls Foundry IQ:

If the knowledge source points to a chunked index, such as one populated through integrated vectorization or a custom Text Split skill, the skillset must also project the sensitivity label to each chunk row. Without this projection, chunk-level references aren't filtered.

For more information, see Use Foundry IQ indexers to ingest Microsoft Purview sensitivity labels.

Enforce document-level permissions at query time

Token-based query enforcement is a cross-cutting capability that applies to the POSIX-like ACL and RBAC scopes, Microsoft Purview sensitivity labels, and SharePoint in Microsoft 365 ACLs patterns. By using native token-based querying, Foundry IQ validates the caller's Microsoft Entra token on each request and trims result sets to only the documents the caller is authorized to read according to the document ACLs, as long as the document ACL metadata is synchronized to the index.

When you attach the user's token to a query request through the x-ms-query-source-authorization header, Foundry IQ:

  1. Extracts the user, group, and scope claims from the token.
  2. Compares those claims to the permission metadata stored alongside indexed documents (ACL entries, RBAC scopes, Purview label assignments, or SharePoint ACLs).
  3. Returns only documents whose synchronized permission metadata grants the caller access.

Permission freshness

Query-time enforcement uses stored permission metadata, but freshness depends on the type of permission. ADLS user and group ACLs are indexed snapshots: ACL-only changes use default-enabled, roughly daily automatic refresh on eligible normal runs, or an explicit permissions resync. Container RBAC scopes identify resources, not role assignments; delegated-user authorization is evaluated separately at query time with propagation and caches. Group membership resolution also has its own propagation and caching behavior.

For SharePoint, incremental processing covers detected item-level changes and supported non-root folder permission changes, including unchanged descendants. Other scopes or missed notifications can require an explicit refresh. See Synchronize permissions between indexed and source content for the scenario table and timing limitations.

Permission refresh doesn't provide immediate revocation or a corpus-wide freshness SLA. For operational steps, failures, chunk consistency, and cleanup, see ADLS synchronization, Blob scope freshness, and SharePoint synchronization. Custom push ingestion remains responsible for synchronizing its own metadata.

For end-to-end query implementation steps, see Query-time ACL and RBAC enforcement in Foundry IQ.

Benefits of document-level access control

Native document-level access control in Foundry IQ delivers concrete advantages over application-side filtering:

  • Reduces custom permission code: Foundry IQ handles supported group resolution and permission filtering during query execution.
  • Aligns with existing compliance controls: Reusing Microsoft Entra, Microsoft Purview, and SharePoint permissions metadata helps keep search results aligned with the source identity system. Review the permission synchronization model for each source to understand its limitations.
  • Honors source permissions after each ACL synchronization: For token-based approaches (ACL, RBAC scopes, Purview labels, SharePoint ACLs), query-time enforcement uses the permission metadata that the documented source-specific synchronization mechanism (indexer run, push-API update, or Purview refresh) already wrote to the index.
  • Improves performance versus post-query trimming: Filtering inside the search pipeline is faster than loading larger result sets into your application and trimming there, especially at high query volumes.
  • Reuses your existing identity infrastructure: Microsoft Entra and SharePoint identities remain the source of truth for access decisions, which reduces identity duplication and the operational overhead of maintaining a parallel permission store.

Tutorials and samples

Explore document-level access control in Foundry IQ with more articles and samples.