Merge pull request #4732 from mattgotteiner/patch-1

Create search-query-acls-rbac-enforcement.md

Author: v-dirichards

articles/search/search-query-access-control-rbac-enforcement.md

@@ -0,0 +1,48 @@
+---  
+title: Query-Time ACL and RBAC Enforcement in ADLS Gen2 Indexes
+titleSuffix: Azure AI Search  
+description: Learn how query-time ACL and RBAC enforcement ensures secure document retrieval in Azure AI Search for indexes containing permission filters from Azure Data Lake Storage (ADLS) Gen2 data sources.  
+ms.service: azure-ai-search  
+ms.topic: conceptual  
+ms.date: 04/23/2025  
+author: mattgotteiner  
+ms.author: magottei 
+---  
+
+# Query-Time ACL and RBAC enforcement in Azure AI Search  
+
+Query-time access control ensures that users only retrieve search results they're authorized to access, based on their identity, group memberships, roles, or attributes. This functionality is essential for secure enterprise search and compliance-driven workflows.  
+
+## Requirements 
+- Azure Data Lake Storage (ADLS) Gen2 data source configured ACLs and/or RBAC roles at container level, or permissions manually pushed into the index.
+- Configure document ACL and RBAC role functionality as required using Azure AI Search [built-in indexers](search-indexer-access-control-lists-and-role-based-access.md) or when indexing the documents [using the API directly](search-index-access-control-lists-and-rbac-push-api.md).
+
+
+## How query-time enforcement works
+
+This section lists the order of operations for ACL enforcement at query time.
+
+### 1. User permissions input  
+The end-user application sends user permission as part of the search query request. The following table lists the source of the user permissions Azure AI Search uses for ACL enforcement:
+
+| Permission type | Source |
+| - | - |
+| userIds | `oid` from `x-ms-query-source-authorization` token |
+| groupIds | Group membership fetched using the [Microsoft Graph](/graph/api/resources/groups-overview) API |
+| rbacScope | Permissions the user from `x-ms-query-source-authorization` has on a storage container |
+
+### 2. Security filter construction  
+Azure AI Search 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.
+
+### 3. Results filtering  
+The security filter efficiently matches the userIds, groupIds, and rbacScope from the user against each list of ACLs in every document in the search index to limit the results returned to ones the user has access to. It's important to note that each filter is applied independently and a document is considered authorized if any filter succeeds. For example, if a user has access to a document through userIds but not through groupIds, the document is still considered valid and returned to the user.
+
+## Limitations
+- If ACL evaluation fails (for example, Graph API is unavailable), the service returns **5xx** and does **not** return a partially filtered result set.
+- Document visibility requires both:
+  - the calling application’s RBAC role (Authorization header), and  
+  - the user identity carried by **x-ms-query-source-authorization**.
+
+## Next steps
+* [How to Index Permission Information](tutorial-adls-gen2-indexer-acls.md) provides a detailed walkthrough of how to set up an index with ACLs using Azure Search indexers.
+* [Indexing ACLs and RBAC using Push API in Azure AI Search](search-index-access-control-lists-and-rbac-push-api.md) provides a walkthrough of how to set up an index with ACLs using the push API.

articles/search/toc.yml

@@ -209,6 +209,8 @@ items:
       href: ./security-controls-policy.md
     - name: Security baseline
       href: /security/benchmark/azure/baselines/cognitive-search-security-baseline?toc=/azure/search/TOC.json
+    - name: Query with permission filters
+      href: search-query-access-control-rbac-enforcement.md
     - name: Document-level security
       href: search-document-level-access-overview.md
 - name: How-to guides