Edit

Troubleshoot SharePoint permission filtering in Azure AI Search

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.

Use this article if query-time permission filtering for indexed SharePoint content returns missing or unexpected results, or if a permission-filtered query fails.

Prerequisites

  • An index populated by the SharePoint in Microsoft 365 indexer with ACL ingestion configured.
  • Query-time permission filtering configured as described in Query-time ACL and RBAC enforcement.
  • REST API version 2026-05-01-preview or an equivalent preview SDK package when you use SharePoint site groups.
  • Access to the index definition, generated or explicit indexer status, and the SharePoint permissions for a test user.
  • Search Index Data Contributor or equivalent elevated-read permission if you need to compare filtered and unfiltered results.

Follow the troubleshooting decision tree

Complete these checks in order. Stop when the observed result identifies the configuration or permission that needs correction.

1. Confirm the failure occurs at query time

This article covers permission filtering after SharePoint content and ACL metadata are indexed.

Continue here only when indexed permission metadata exists and the symptom occurs when you query it.

2. Identify the three identities

Record which identity fills each role. Don't substitute one identifier for another.

Identity Purpose Where to verify it
Querying user The delegated user token in x-ms-query-source-authorization determines which protected documents the user can retrieve. Your application authentication flow and the query request.
SharePoint connector app registration The sharePointConnectorAppRegistration on the index lets Azure AI Search resolve the querying user's SharePoint site group memberships. The index definition and the app registration described in Configure SharePoint groups support.
Azure AI Search request identity The Microsoft Entra bearer token in the Authorization header, or the API key in the api-key header, authenticates the request to the search service. The identity must have permission to query the index. Your query client and Azure AI Search data plane role assignment.

3. Check the permission-filter configuration

Compare the index, indexer, and generated objects against their owner articles.

  1. Confirm the index has permissionFilterOption set to enabled.
  2. Confirm UserIds and GroupIds have the correct permissionFilter values.
  3. For SharePoint site groups, confirm the index has sharePointConnectorAppRegistration and a SharePointSiteUrl field with sharepointSiteUrl: true.
  4. Confirm every indexed document or chunk carries the applicable permission fields. If the skillset uses index projections, verify the ACL fields are in indexProjections.mappings.

If any value is absent, return to Configure your search service for ACL ingestion and query-time enforcement.

4. Check the query token safely

Never log, paste into a support request, or share a full access token. Decode only the token payload locally, and sanitize identifiers before you capture diagnostic output.

  1. Confirm the request includes x-ms-query-source-authorization with a current delegated token for the test user.
  2. Decode the payload locally and confirm the oid identifies the intended test user. Record a sanitized value such as <test-user-object-id>.
  3. Reauthenticate the user and retry if the token is missing or expired.

If the user token is omitted, permission-protected content isn't returned. The Authorization header alone doesn't replace x-ms-query-source-authorization.

5. Check Microsoft Entra permissions

  1. Confirm the indexed UserIds or GroupIds contain the expected Microsoft Entra object ID. Use an elevated-read query only for this diagnostic comparison.
  2. Confirm the test user has a direct assignment or reaches the assigned Microsoft Entra group through transitive Microsoft Entra group membership.
  3. If the Microsoft Entra group is nested within a SharePoint group, change the assignment. This mixed relationship isn't expanded and can cause missing results. Add the user directly to the SharePoint group, or grant permission through a supported Microsoft Entra group assignment.

For the exact support boundary, see Supported group relationships.

6. Check SharePoint site group permissions

Complete this step when the document ACL depends on an Owners, Members, Visitors, or custom SharePoint site group.

  1. Use an elevated-read query to confirm GroupIds contains the expected spg:-prefixed group ID and SharePointSiteUrl identifies the source site.
  2. Confirm the test user is a direct member of that SharePoint group.
  3. Confirm the index's sharePointConnectorAppRegistration uses the identifiers and permissions required by SharePoint groups support.

If the indexed fields are empty or stale, fix ingestion or synchronize the SharePoint permissions before you retest the query.

7. Check the query request

  1. Use REST API version 2026-05-01-preview or an equivalent preview SDK package for SharePoint site-group permission filters.
  2. Confirm Authorization authenticates a principal that can query the index.
  3. Confirm x-ms-query-source-authorization contains the delegated test-user token.
  4. Retry the same query without unrelated filters or ranking changes so you can isolate permission behavior.

Use the general query example as the request-shape owner. Don't include full tokens in saved requests or logs.

8. Compare expected and actual results

  1. Choose one document the test user can access and one document the user can't access in SharePoint.
  2. Run the permission-filtered query as the test user and record only document keys or other nonsecret identifiers.
  3. Run an elevated-read query and compare the stored UserIds, GroupIds, and SharePointSiteUrl values with the source permissions.
  4. If elevated read returns the expected document but the user query doesn't, focus on the user token and group resolution. If elevated read also misses it, focus on ingestion, mappings, and ACL synchronization.

Elevated read is for investigation. Don't use it to return unrestricted results to end users.

9. Capture request correlation details

If the query still fails, capture the API version, UTC timestamp, sanitized request body, HTTP status, response headers, and any request or correlation ID returned by the service. Include the index name and whether the same document appears under elevated read.

Remove access tokens, API keys, secrets, user names, and tenant-specific URLs before you share diagnostics with Microsoft Support.

Related content

  • Last updated on