Tutorial: Index ADLS Gen2 permissions and verify filtered results

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.

This tutorial demonstrates Azure Data Lake Storage (ADLS) Gen2 permission metadata ingestion, in which a Foundry IQ (Azure AI Search) indexer adds access control lists (ACLs) and role-based access control (RBAC) scope to a search index. This functionality is generally available in REST API 2026-10-01.

It also shows you how to query as allowed and denied users and verify permission changes after indexing.

For more information about indexing ACLs, see Use an ADLS Gen2 indexer to ingest permission metadata.

In this tutorial, you learn how to:

  • Configure RBAC scope and ACLs on an adlsgen2 data source
  • Create a Foundry IQ index containing permission information fields
  • Create and run an indexer to ingest permission information into an index from a data source
  • Search the index you just created

Use a REST client and REST API 2026-10-01. Currently, there's no support for ACL indexing in the Azure portal.

Prerequisites

  • An Azure account with an active subscription. Create an account for free.

  • Microsoft Entra ID authentication and authorization. Services and apps must be in the same tenant. Role assignments are used for each authenticated connection. Users and groups must be in the same tenant. You should have user and groups to work with. Creating tenants and security principals is out-of-scope for this tutorial.

  • ADLS Gen2 with a hierarchical namespace.

  • Files in a hierarchical folder structure. This tutorial assumes the ADLS Gen2 demo of folder structure for file /Oregon/Portland/Data.txt. This tutorial guides you through ACL assignment on folders and files so that you can complete the exercise successfully.

  • Foundry IQ, any region. Basic tier or higher is required for managed identity support.

  • Visual Studio Code with the REST Client extension.

Prepare sample data

Create a container named parks in ADLS Gen2. Upload two plain-text files with different content:

  • Oregon/Portland/Data.txt
  • Washington/Seattle/Data.txt

This tutorial uses the default parsing mode to create one search document per file. The index stores the file name and extracted text. The .txt files don't require the specialized text parsing mode, which isn't supported with document-level permissions. See Supported parsing and content extraction for permission ingestion.

Check Foundry IQ service configuration

Configure your Foundry IQ service for Microsoft Entra ID authentication and authorization. Review this checklist to ensure you're prepared.

Get a personal identity token for local testing

This tutorial assumes a REST client on a local system, connecting to Azure over a public internet connection.

Follow these steps to acquire a personal identity token and set up Visual Studio Code for local connections to your Azure resources.

Set permissions in ADLS Gen2

As a best practice, use Group sets rather than directly assigning User sets.

  1. Grant the Foundry IQ service identity read access to the container. The indexer connects to Azure Storage under the Foundry IQ service identity. The Foundry IQ service must have Storage Blob Data Reader permissions to retrieve data.

  2. Grant per-group or user permissions in the file hierarchy. In the file hierarchy, identify all Group and User sets that are assigned to containers, directories, and files.

  3. You can use the Azure portal to manage ACLs. In Storage Browser, select the Oregon directory and then select Manage ACL from the context menu.

  4. Add new security principals for users and groups.

  5. Use named users and named groups for the test grants. Owning-user, owning-group, and Other entries aren't supported for ACL indexing; don't rely on them for the test identities.

Before indexing, check the source ACLs for unsupported implicit blocklists and remediate them with supported allowlists.

Create a search index for permission metadata

Create an index that contains fields for content and permission metadata.

Use REST API 2026-10-01 for the index, data source, and indexer requests.

For demo purposes, the permission field has retrievable enabled so that you can check the values from the index. In a production environment, you should disable retrievable to avoid leaking sensitive information.

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "metadata_storage_path", "type": "Edm.String",
      "searchable": false, "filterable": true, "retrievable": true
    },
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "content", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": false
    },
    {
      "name": "id", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": false, "filterable": true, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

Create a data source

Modify data source configuration to specify indexer permission ingestion and the types of permission metadata that you want to index.

A data source needs indexerPermissionOptions.

In this tutorial, use a system-assigned managed identity for the authenticated connection.

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "parks",
    "query": null
    }
}

Create and run the indexer

Define top-level fieldMappings for the raw source path and permission metadata. metadata_storage_path is required even if you ingest only RBAC scopes. Don't encode this field.

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "refreshAllAcls": true
    }
  },
  "fieldMappings": [
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "id", "mappingFunction": { "name": "base64Encode" } },
    { "sourceFieldName": "metadata_storage_name", "targetFieldName": "name" },
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "metadata_storage_path" },
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Creating the indexer starts its first run. Before querying, use Get Indexer Status to confirm that the run completed successfully. Inspect errors and warnings, and verify that both files were indexed.

If you plan to use automatic ACL refresh to verify permission changes, configure an indexer schedule.

Run a query to check results

Now that documents are loaded, you can issue queries against them by using Documents - Search Post (REST).

The URI is extended to include a query input, which is specified by using the /docs/search operator. The query token is passed in the request header. For more information, see Query-time ACL and RBAC enforcement.

POST  {{endpoint}}/indexes/my-adlsgen2-acl-index/docs/search?api-version=2026-10-01
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{query-user-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,content,metadata_storage_path,GroupIds"
}

The Authorization header authorizes your application to query Search. query-user-token is the delegated user's token for permission evaluation; it can represent a different identity.

Verify permission changes

  1. Query as a named user with file read access and execute/traverse access through the ancestor directories. Confirm that the expected document appears.
  2. Query as a user with no matching user or group ACL and no supported container RBAC grant. Confirm that the same document is absent.
  3. Remove the first user's ACL grant without changing file content. Ensure that no other ACL or supported RBAC grant authorizes that user. Request a permissions resync and run the indexer, or await an eligible automatic ACL refresh.
  4. After completion, repeat both queries. The revoked user must no longer retrieve the document, while another explicitly authorized user still can.
  5. Repeat with a named-group grant or removal and an ancestor-directory traversal change. Test RBAC grants or removals separately, allowing for Storage propagation and query authorization caches.

For a chunked pipeline, also verify representative chunks from each affected parent. After partial failures, inspect errors and warnings and retry before treating all results as reconciled. Use the canonical projection mappings; a protected parent alone doesn't protect a chunk missing permission metadata.