Preserve OneLake permissions in Foundry IQ (Azure AI Search) (preview)

Configure a OneLake indexer or indexed OneLake knowledge source to preserve Microsoft OneLake permissions. Foundry IQ (Azure AI Search) indexes source-location metadata rather than user and group ACLs, and uses OneLake to evaluate the requesting user's access at query time.

This article supplements Index OneLake files and Create an indexed OneLake knowledge source with the configuration specific to permission ingestion. Manage source permissions in Microsoft Fabric.

This preview is supported only in Azure public cloud.

Important

OneLake permission ingestion is in Public Preview and is subject to the Supplemental Terms of Use for Microsoft Azure Previews.

For preview terms specific to this feature, see Preview functionality.

For terms that apply when you connect to external data sources, see External data sources.

Prerequisites

Configure a OneLake indexer

For a directly managed indexer pipeline, add the following settings to the standard OneLake indexing configuration. These settings are configuration additions, not complete create requests.

  1. Set indexerPermissionOptions on the data source to select the source-location metadata to ingest. Select oneLakeParentFolders and oneLakeLakehouseId independently for ingestion. The following JSON fragment selects both for permission-aware retrieval:

    {
      "indexerPermissionOptions": [
        "oneLakeParentFolders",
        "oneLakeLakehouseId"
      ]
    }
    
  2. Define the corresponding fields in the target index.

    Source metadata Example target field Index field type Required field configuration
    metadata_onelake_parent_folders onelake_parent_folders Collection(Edm.String) filterable: true; permissionFilter: "oneLakeParentFolders".
    metadata_onelake_lakehouse_id onelake_lakehouse_id Edm.String filterable: true; permissionFilter: "oneLakeLakehouseId".
    metadata_onelake_is_shortcut metadata_onelake_is_shortcut Edm.Boolean A top-level field with filterable: true and no permissionFilter annotation. Keep this field name.

    The lakehouse ID identifies the configured source lakehouse, not a shortcut's target lakehouse.

  3. Set the index's permissionFilterOption to enabled and configure oneLakeSecuritySource with the source workspace and lakehouse IDs:

    {
      "permissionFilterOption": "enabled",
      "oneLakeSecuritySource": {
        "fabricWorkspaceId": "<fabric-workspace-id>",
        "lakehouseId": "<lakehouse-id>"
      }
    }
    

Don't substitute userIds or groupIds for the OneLake permission options. These fields represent source locations, not copied user and group ACL entries.

Keep the source-provided values. Don't replace them with skill outputs, mapping functions, or fields derived from document content.

Project fields into chunks

When a skillset creates chunks, map all three metadata fields onto each chunk through index projections. These projection mappings populate the chunk fields directly; you don't need indexer fieldMappings for them.

  1. Add the three fields in the preceding table to the chunk index. Configure that index's permissionFilterOption and oneLakeSecuritySource as described earlier.

  2. Add the following fragment to your skillset. It uses the standard chunk index schema with a parent_id field and a Text Split skill that produces /document/pages/*. Keep your other content mappings when adapting the example.

    {
      "indexProjections": {
        "selectors": [
          {
            "targetIndexName": "<chunk-index-name>",
            "parentKeyFieldName": "parent_id",
            "sourceContext": "/document/pages/*",
            "mappings": [
              {"name": "chunk", "source": "/document/pages/*"},
              {
                "name": "onelake_parent_folders",
                "source": "/document/metadata_onelake_parent_folders"
              },
              {
                "name": "onelake_lakehouse_id",
                "source": "/document/metadata_onelake_lakehouse_id"
              },
              {
                "name": "metadata_onelake_is_shortcut",
                "source": "/document/metadata_onelake_is_shortcut"
              }
            ]
          }
        ],
        "parameters": {"projectionMode": "skipIndexingParentDocuments"}
      }
    }
    

By using skipIndexingParentDocuments, you write only chunks. Each written content index needs all three metadata fields. Map them directly from their corresponding /document/metadata_onelake_* sources shown earlier in every content projection.

Map fields for document indexing

For nonchunked ingestion or a separate parent index, matching source and target names with compatible types map automatically. Use indexer field mappings only to rename these metadata fields, such as metadata_onelake_parent_folders to onelake_parent_folders and metadata_onelake_lakehouse_id to onelake_lakehouse_id in the example schema. The unchanged metadata_onelake_is_shortcut name doesn't need an explicit field mapping.

Adding permission fields to an existing index doesn't populate them in documents already indexed. After configuring permission ingestion, reprocess those documents to populate the required metadata.

Configure an indexed OneLake knowledge source

When you create an indexed OneLake knowledge source, set both values in indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions:

{
  "ingestionPermissionOptions": [
    "oneLakeParentFolders",
    "oneLakeLakehouseId"
  ]
}

This JSON fragment shows only the permission setting. Unlike the direct data-source options, both values are required together for secured indexed OneLake ingestion. For the complete REST creation example using 2026-11-01-preview and both permission options, see Create a knowledge source with OneLake permission preservation.

The knowledge source generates the index fields, index-level permission configuration, field mappings, and chunk projections. You don't need to configure those generated mappings separately.

With OneLake permission ingestion enabled, omit the asset store, enrichment cache, and graph extraction settings.

Query with the requesting user's identity

Use the existing ACL query and testing flow, including x-ms-query-source-authorization for the requesting user's token. Use 2026-11-01-preview for OneLake permission-aware requests instead of the API version in those shared examples. For a knowledge base, follow the shared query-time authorization guidance. OneLake doesn't require a separate query protocol.

Search evaluates the requesting user's readable OneLake folders against the indexed parent-folder values, within the configured lakehouse. A match with a document's immediate parent or an ancestor folder can make that document eligible for retrieval. Source permissions remain managed in Fabric.

For Files/teamA/reports/document.txt, the indexed folder values are ["Files", "Files/teamA", "Files/teamA/reports"]. The filename isn't included. The hierarchy includes ancestors above a configured ingestion subfolder.

Paths are lakehouse-relative, use / separators, and have no leading or trailing slash. Matching is case-sensitive. Preserve spaces, Unicode characters, and literal percent characters as supplied; don't URI-decode or otherwise rewrite these metadata values.

Account for permission and path freshness

Indexed source locations and query-time access information can change at different times. Permission changes, including revocations, can take time to affect retrieval; there isn't a fixed end-to-end freshness interval.

Queries use indexed content and query-time authorization; they don't trigger an indexer run. Indexers normally run on creation unless disabled, and subsequently on demand or on a schedule. A scheduled time or run request isn't a completion deadline. See scheduling behavior for delayed or skipped starts.

Stage What can delay a change
Fabric and OneLake Propagation of workspace roles, item access, and folder permissions.
Indexer start Scheduling and execution capacity; a scheduled or requested run might not start immediately.
Indexer run Processing duration, throttling, retries, or failed items.
Index availability Chunk projection, document writes, and index refresh affect when updated content and path metadata become searchable.
Requesting-user identity Token freshness and changes to the user's roles or group membership.
Query-time access Cached OneLake access information can continue to reflect earlier permissions until refreshed. A new user token alone doesn't clear that cached information.

Use indexer status and execution history to check run-level start and end times, errors, warnings, and failed items. The top-level running status means the indexer is available to run, not that a run is in progress. Check representative documents and chunks for the required metadata. A successful ingestion run doesn't establish that Fabric propagation, user tokens, and cached access information have also refreshed.

After a move, rename, deletion, or path reuse, check for stale records at the old location as well as records at the new location. Older indexed content can remain associated with a path whose current access has changed.

Use the OneLake soft-deletion workflow before physically removing a source file. If the source file is already removed, manually delete the orphaned search documents and chunks.

Follow the run and reset guidance to reprocess files that still exist. Resetting an indexer doesn't delete its indexed documents or refresh query-time access information.

When validating a permission change, use fresh user tokens and the shared ACL testing flow. Compare an allowed and a denied user, and check both parent documents and chunks where applicable. Don't use ingestion completion as the measure of revocation completion.

Understand shortcut permission boundaries

OneLake permission-aware retrieval doesn't support shortcuts in this preview. Shortcut-derived content is excluded from results, including content reached through OneLake-to-OneLake and external shortcuts. Access to the containing folder or shortcut target doesn't enable retrieval of shortcut content.

Ordinary shortcut ingestion support is separate from permission-aware retrieval.

The required metadata_onelake_is_shortcut field distinguishes shortcut-derived content from direct files. Define it as a top-level Edm.Boolean field with filterable: true and no permissionFilter annotation. Keep this field name and its source-provided values. Missing or null values don't qualify a document for permission-filtered results. Don't replace this field with a constant value or infer it from parent-folder access.

Counts, facets, citations, and grounding based on permission-filtered content aren't a listing of all indexed content.

Troubleshoot permission-aware retrieval

For missing results, check the following source-specific conditions before using the shared query troubleshooting guidance:

  • Confirm the three required fields exist and have the types and attributes shown earlier. For chunks, check each projection's mappings and source paths.
  • Check the Foundry IQ service's system-assigned managed identity and its Fabric workspace Admin role.
  • Check whether the content came through a shortcut. Shortcut exclusion is a preview limitation, not a missing parent-folder grant.
  • Check path freshness, case, and the configured lakehouse after moving content or changing permissions.
  • If OneLake access resolution fails because of authentication, pagination, an invalid response, or path resolution, the query returns an error rather than proceeding with incomplete access information. Correct the source access or configuration before retrying.

Limitations

Built-in text and embedding skills are supported with OneLake permission ingestion. The following preview constraints apply:

  • Shortcut-derived content is excluded from permission-aware retrieval. See shortcut permission boundaries.
  • With either OneLake permission option enabled, enrichment caching, knowledge stores, and custom Web API skills aren't supported.
  • Chat Completion skills require a supported Microsoft endpoint for OneLake permission ingestion; custom-domain and Azure API Management endpoints aren't supported. If you also enable sensitivity-label ingestion, Chat Completion skills aren't supported with any endpoint.