Query-time ACL and RBAC enforcement 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.

SharePoint ACL permission filtering, ADLS Gen2 ACL/RBAC filtering, standard Blob container RBAC filtering, and elevated read are generally available with the 2026-10-01 data plane REST API.

Query-time access control filters search results by using the delegated user's identity and the index's supported permission metadata. Push ACL ingestion is generally available. Microsoft Purview sensitivity label enforcement remains in preview.

Authorized access depends on permission metadata that's ingested during indexing. For indexer data sources that have built-in access models, such as Azure Data Lake Storage (ADLS) Gen2 and SharePoint in Microsoft 365, an indexer can pull in the permission metadata for each document automatically. For other data sources, you must assemble the document payload yourself, and the payload must include both content and the associated permission metadata. You then use the push APIs to load the index.

This article explains how to set up queries that use permission metadata to filter results.

OneLake source permissions reuse the x-ms-query-source-authorization caller-token flow. For their source-location metadata requirements and authorization model, rather than the copied ACL/RBAC model described below, see Preserve OneLake permissions.

Prerequisites

  • Enable permissionFilterOption on the index, and use top-level, filterable permission fields. You don't add the permission filter to your queries; the search engine builds it internally.

  • Use permission metadata appropriate to your source: user and group IDs for SharePoint, POSIX-style ACLs for ADLS Gen2, or container resource IDs for ADLS Gen2 or standard Blob Storage RBAC scopes.

  • For ACL-based enforcement with custom ingestion, store userIds and groupIds as Microsoft Entra object IDs (GUIDs), not email addresses or UPNs. At query time, Foundry IQ (Azure AI Search) uses the delegated user token in x-ms-query-source-authorization to evaluate document permissions. For field types and schema details, see Index document ACLs with the push REST APIs.

  • Depending on the data source:

  • Use REST API 2026-10-01 for SharePoint and ADLS/Blob permission-filtered queries, or verify equivalent SDK support in the package changelog. For independent preview scenarios, use their documented API versions.

Limitations

  • Unresolved group memberships don't grant access. For SharePoint, independently resolved grants can still apply when a group lookup fails. If the request returns an authorization error, don't retry with unfiltered or elevated access.

  • For copied ACL and RBAC metadata, freshness depends on how each ingestion method propagates permission changes to the index:

    • A SharePoint indexer refreshes detected item-level changes and supported non-root folder permission changes during successful incremental processing. Configure a short recurring schedule for permission refresh. The interval isn't a completion deadline or revocation SLA. The linked guidance also covers other scopes and explicit refresh options.
    • An ADLS Gen2 indexer refreshes ACLs on eligible normal runs roughly daily by default, or through an explicit permissions resync.
    • Blob and ADLS RBAC scope checks evaluate the delegated user's container authorization at query time. Role assignment propagation and authorization caches are separate from indexed ACL freshness.
    • Custom or push ingestion requires you to reingest the affected documents.
  • For OneLake source-location metadata and query-time access information, see Permission and path freshness.

  • Queries without elevated read require both:

    • The caller's Search RBAC authorization (Authorization header).
    • The delegated user identity carried by x-ms-query-source-authorization for permission-protected content.
  • Initial ACL-based queries might experience higher latency compared to subsequent requests, due to caching and permission resolution overhead.

  • For indexed SharePoint content, Microsoft Entra groups nested within SharePoint groups are supported within five levels, subject to a separate site-level principal limit. See Supported group relationships.

ACL entry limits per data source

Access control list (ACL) entry limits define how many distinct permission records can be associated with a file, folder, or item within a connected data source. Each entry represents a single user or group identity and the access rights granted to that identity (for example, Read, Write, or Execute).

The maximum number of ACL entries supported by Foundry IQ functionality varies depending on the data source type:

Azure Data Lake Storage Gen2 (ADLS Gen2): Each file or directory can have up to 32 ACL entries permissions. In this context, an entry means a single principal (user or group) with a specific permission set. Example: assigning "Everyone" read access and "Azure users" execute access would count as two ACL entries.

SharePoint in Microsoft 365: SharePoint data source in search supports up to 1,000 permission entries per file. Each entry represents a unique user or group assignment in the item's permission list. This is distinct from the overall unique permission scopes limits per list or library, which governs how many items can have unique permissions.

These limits determine how granularly Foundry IQ can honor item-level permissions when indexing or filtering search results. If an item exceeds these ACL entry limits, permissions beyond the limit might not be enforced at query time.

How query-time enforcement works

This section lists the order of operations for ACL enforcement at query time. Operations vary depending on whether you use Azure RBAC scope or Microsoft Entra ID group or user IDs.

1. User permissions input

For native permission-filtered queries, the two token positions have separate roles:

  • Authorization authenticates the caller and authorizes the Search data-plane operation through Search RBAC. The caller can be a user, an application service principal, or a managed identity with the required Search role and resource scope.
  • x-ms-query-source-authorization carries a delegated user access token. Foundry IQ evaluates that user's document permissions, not the document permissions of the application in Authorization.

An application or managed identity authorized to call Search isn't automatically a supported document-permission subject. The identity used by an indexer to read a source is also separate from the querying caller and the user whose permissions are evaluated.

The following table describes the supported delegated-user flows. Each flow retains its source-specific permission and API limits.

Permission flow Supported delegated-user behavior
userIds ACLs Matches the delegated user's Microsoft Entra object ID (oid) from x-ms-query-source-authorization against indexed user ACLs.
groupIds ACLs Resolves the user's Microsoft Entra group memberships through Microsoft Graph, including supported security groups and Microsoft 365 Groups, and matches their object IDs against indexed group ACLs.
SharePoint site groups Resolves the delegated user's site group memberships through the registered application on the index. Matches spg:-prefixed IDs in groupIds. Requires the SharePoint groups configuration. Use REST API 2026-10-01 for SharePoint permission filtering.
rbacScope Evaluates the delegated user's supported Blob-read authorization on the indexed ADLS Gen2 or standard Blob container scopes.
Purview sensitivity labels (preview) Evaluates the delegated user's label permissions under the separate Purview requirements.

Microsoft Entra group expansion uses the query-source user token in a user on-behalf-of (OBO) flow. Groups aren't token-bearing identities. An application token in Authorization doesn't replace the delegated user assertion required by this group-resolution flow. For supported group relationships, see the source-specific limits.

Application-token boundaries

Choose the token flow for the operation and permission model, not just for the application's ability to authenticate to Search.

Flow Application-token boundary
Search caller authentication An application service principal or system-assigned or user-assigned managed identity can authenticate the caller with the required Search role. This doesn't make it the document-permission subject.
userIds, groupIds, and SharePoint site groups Use the delegated query-source user flow described above. An application object ID in a token or ACL doesn't establish a supported app-only query-source flow. Group expansion still requires its documented user assertion and consent.
Organization-wide permission values A broadly applicable grant doesn't change the token contract. Don't omit the required user token or substitute an application token solely because the content has an organization-wide grant.
Container rbacScope Use the supported delegated-user flow. Assigning a storage role to an indexer or application doesn't substitute for the querying user's authorization.
OneLake source permissions Follow the source-specific preview contract and pass the requesting user's token. Search's managed identity authenticating to OneLake is separate from that user.
Purview labels Follow the separate delegated-user requirements, including the delegated-user requirement for elevated read on a Purview-enabled index.
Elevated read without Purview An authorized application can use app-only caller authentication for the direct-index administrative operation. This bypasses document-permission filtering; it doesn't evaluate application ACL membership.
Application-managed security string filters The application authenticates its users and constructs trusted filters itself. This isn't native application-token permission evaluation.

Don't infer additional permission-subject support from oid or tid claims, workload identity federation, an agent identity, or an app-to-app OBO configuration. Use the identity-acquisition flow, consent, API version, and operation documented for the specific feature.

Direct Search queries and Get Document, knowledge-base retrieval, and MCP/agentic access have separate contracts. Support on one surface doesn't establish the same headers, identity types, or administrative bypass on another. For knowledge-base and MCP access, follow query-time retrieval authorization; citations don't provide a separate authorization path.

If a request rejects the supplied token or actor, fail the application request safely. Don't retry by omitting the user token, switching subjects, returning unfiltered or public-only results, or enabling elevated read.

2. Security filter construction

Internally, Foundry IQ dynamically constructs security filters based on the user permissions provided. These security filters are automatically appended to any filters that might come in with the query if the index has the permission filter option enabled.

For Azure RBAC, the index stores container resource IDs, not copied role assignments. Foundry IQ evaluates the delegated user in x-ms-query-source-authorization for supported Blob-read authorization on those scopes. This user isn't necessarily the application principal in Authorization, which independently authorizes access to the Search data plane. Authorization resolution uses caches; reindexing doesn't force those caches to refresh.

3. Results filtering

The ACL/RBAC security filter matches the user's permissions against the indexed userIds, groupIds, and rbacScope fields. These grants are evaluated independently: any matching supported grant satisfies this filter. For example, a matching userIds grant doesn't also require a matching groupIds grant. Purview label enforcement has separate requirements.

This any-grant behavior requires successful permission evaluation. A failure resolving groups or another configured permission flow can fail the request even if a direct user ACL or RBAC grant could match.

When testing revocation, exclude alternate supported grants. Removing an ACL grant doesn't deny access if a container RBAC grant still authorizes the user. If permission evaluation fails, fail the application request safely; don't retry without the delegated token or enable elevated reads as a fallback.

For ADLS Gen2, unsupported implicit blocklists grant no ACL-derived access, but independent supported RBAC grants can still authorize access.

These native permission checks also apply to moreLikeThis: the source document must be readable before similarity retrieval runs, and candidate documents are filtered independently. If the source document is unreadable or missing, the request returns an empty search result, not an operation-authorization failure. Purview-enabled indexes separately reject moreLikeThis.

SharePoint groups at query time

Foundry IQ can evaluate SharePoint site group permissions, such as Owners, Members, Visitors, and custom site groups, at query time by using REST API 2026-10-01. To enable this scenario, the index must include:

  • A sharePointConnectorAppRegistration property that specifies the ingestion application's client ID and the managed identity's application ID for federated authentication.
  • A field marked with the sharepointSiteUrl: true attribute that stores the SharePoint site URL for each indexed item (typically named SharePointSiteUrl and populated from the metadata_spo_site_url source field).

At query time, Foundry IQ uses the registered application and the site URL on each candidate document to resolve the SharePoint group memberships of the calling user on that site. The resolved groups are matched against the spg:-prefixed values stored in the groupIds permission filter field. The spg: prefix distinguishes SharePoint site groups from Microsoft Entra group object IDs, which are stored without a prefix.

For configuration details and limitations, see Configure SharePoint groups support.

If SharePoint permission filtering returns missing or unexpected results, see Troubleshoot SharePoint permission filtering.

Example: Query with SharePoint site group enforcement

The request is identical to the standard ACL-enforced query. The Foundry IQ service uses the index's sharePointConnectorAppRegistration to resolve SharePoint group membership on the caller's behalf. Replace <SEARCH_SERVICE_ENDPOINT> with your endpoint, <INDEX_NAME> with the index name, and <USER_ACCESS_TOKEN> with the raw delegated user token. To inspect stored permission metadata, follow the ACL ingestion verification steps rather than exposing ACL fields in ordinary user queries.

POST <SEARCH_SERVICE_ENDPOINT>/indexes('<INDEX_NAME>')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json

{
    "search": "*",
    "select": "name,description",
    "orderby": "name asc"
}

Query example

Use the 2026-10-01 index and four-document payload from the push indexing workflow. Wait until the documents are searchable. Replace <SEARCH_SERVICE_ENDPOINT> with your endpoint and <USER_ACCESS_TOKEN> with the raw delegated user token for the <USER_OBJECT_ID> used in the upload. Use a caller token authorized to query the index.

POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json

{
    "search": "*",
    "select": "id,content",
    "top": 4,
    "count": true,
    "orderby": "id asc"
}

Reference: Search Documents.

Elevated permissions for investigating incorrect results

Elevated read is generally available in REST API 2026-10-01. Use it only for authorized administrative investigations, not as a fallback for end-user queries.

An elevated-read request returns matching documents regardless of document-level permission filters. Set x-ms-enable-elevated-read: true to inspect indexed content when investigating missing or unexpected results.

For indexes without Purview enabled, an application service principal can use an app-only access token in Authorization for elevated read. Assign the caller the required elevated-read permissions. This bypasses document-permission filtering; it doesn't evaluate the application as a document-permission subject.

Don't include x-ms-query-source-authorization in an elevated-read request. To compare results against an end user's view, issue a separate ordinary query with that user's token and without the elevated-read header.

For Purview-enabled indexes, elevated read requires a delegated user token in Authorization; app-only tokens aren't supported for that flow. See Purview elevated-read requirements.

Permissions for elevated-read requests

The caller in Authorization must have Search Index Data Contributor permissions or a custom role that includes the Elevate Read permission.

Queries are a data plane operation, so the custom role can only consist of atomic data plane permissions. For a custom role, add the Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read permission.

Add an elevated-read header to a query

After you set up permissions, you can run the query. The following example is a query request against a search index.

POST {endpoint}/indexes('{indexName}')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {AUTH_TOKEN}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Important

The 2026-10-01 REST API supports x-ms-enable-elevated-read on Search GET, Search POST, and Get Document actions. For knowledge-base investigations, send the request directly to the underlying search index. The knowledge base retrieve REST API doesn't declare this header. Sensitivity label enforcement retains its separate preview requirements.

Important ACL functionality behavior change in specific preview API versions

Before REST API version 2025-11-01-preview, earlier preview versions 2025-05-01-preview and 2025-08-01-preview returned all documents when using a service API key or authorized Entra roles, even if no user token was provided. Applications that didn't validate the presence of a user token could inadvertently expose results to end users if not implemented correctly or following best practices.

Starting in November 2025, this behavior changed:

  • ACL permission filters now apply even when using only service API keys or Entra authentication across all versions that support ACL.
  • If the user token is omitted, ACL-protected content isn't returned.
  • To view all documents for troubleshooting, you must explicitly include the elevated-read header when using REST API version 2026-05-01-preview or later.

This update helps keep content protected when applications don't enforce best practices for token validation.