Use a SharePoint indexer to ingest permission metadata and filter search results based on user access rights

This article explains how to ingest an access control list (ACL) alongside other content from SharePoint in Microsoft 365 using an Azure AI Search indexer. Permissions from SharePoint are preserved as permission metadata for each indexed document. When users query an index containing content from SharePoint, their search results consist of only those documents for which they have permission to access.

Prerequisites

• Azure AI Search on a billable tier (Basic or higher) in any region.

• SharePoint in Microsoft 365 sites, libraries, folders, and files with configured permissions.

• Complete all configuration steps in the SharePoint indexer documentation, applying the ACL-specific requirements described in this article.

• Configure application permissions with Files.Read.All and Sites.FullControl.All (or Sites.Selected instead of Sites.FullControl.All) to index only the content and permissions of specific sites. Then, grant the application full control permissions for those selected sites.

• REST API version 2025-11-01-preview or an equivalent preview SDK package.

Limitations

• During public preview, ACL ingestion applies to initial indexing only. ACLs are captured on the first ingestion of each file. If permissions change in the source, you must explicitly reindex those documents or their respective ACLs.

• The Azure portal doesn't support this feature.

• The following aren't supported in this preview:

  • SharePoint Information Management policies applicable to user access.

  • Shareable links scoped to "Anyone" or "People in your organization." Only links scoped to "Specific people" are supported.

  • SharePoint groups that can't be resolved to Microsoft Entra groups (such as Owners, Members, Visitors groups).

Support for the SharePoint permission model

This preview supports only basic ACLs for documents, as shown in the following table. The SharePoint indexer doesn't support lists ingestion, so it excludes lists permissions.

How hierarchical permissions are evaluated

SharePoint permissions inherit the hierarchy of Site → Library → Folder → File, unless inheritance is broken.

During ingestion, the indexer gathers user and group identifiers (ID) at each level and computes the effective ACL for each file.

Configure your search service for ACL ingestion and honoring at query time

These steps configure your search service for ACL ingestion and enable ACL honoring at query time.

1. Data source configuration

Set indexerPermissionOptions in the data source definition to allow indexing of userIds and groupIds from SharePoint documents.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. Add permission fields to the index definition

Add fields to your index schema definition to store ACLs and support query-time filtering.

{
  "fields": [
    { "name": "UserIds",  "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Set retrievable attribute to true only during development to verify values. You can change retrievable from true to false with no index rebuild requirement.

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

If your indexer uses a skillset with data chunking, such as a split skill when enabling integrated vectorization, make sure to map ACL properties to each chunk using index projections.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2025-11-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" }, // <-- parent → child
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" } // <-- parent → child
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

4. Configure the indexer field mappings for ACLs

Besides your required indexer configuration, map raw metadata ACL fields from SharePoint to your index fields.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

Synchronize permissions between indexed and source content

During public preview when the configuration is completed, and ACLs are captured during the first indexer run and for new files only. To pick up later changes:

Reset specific documents

You can reset specific documents to fully ingest again content and ACLs.

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2025-11-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

Resync ACLs across the full data source

You can resync the full data set ACL content after initial ingestion.

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2025-11-01-preview
{
  "options": ["permissions"]
}

After indexing your data and ACLs, you can query the index.

Related content

• Index SharePoint content in Azure AI Search (preview)
• Query-time ACL enforcement