Skip to content

Commit 8bd3bdc

Browse files
AnnaMHuffAnnaMHuff
authored
Merge pull request #5908 from vaishalishah11/main
Adding documentation for supporting Rbac Scope ingestion for Azure Blobs
2 parents 518f1d1 + 846493f commit 8bd3bdc

File tree

3 files changed

+168
-1
lines changed

3 files changed

+168
-1
lines changed

‎articles/search/search-blob-indexer-role-based-access.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: Use a Blob indexer to ingest RBAC scopes metadata
3+
titleSuffix: Azure AI Search
4+
description: Learn how to configure Azure AI Search indexers for ingesting Azure Role-Based Access (RBAC) metadata on Azure Blobs.
5+
ms.service: azure-ai-search
6+
ms.topic: how-to
7+
ms.date: 07/07/2025
8+
author: vaishalishah
9+
ms.author: vaishalishah
10+
---
11+
12+
# Use a Blob indexer to ingest RBAC scopes metadata
13+
14+
[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
15+
16+
Starting in 2025-05-01-preview, you can now include RBAC scope alongside document ingestion in Azure AI Search and use those permissions to control access to search results.
17+
18+
You can use the push APIs to upload and index content and permission metadata manually see [Indexing Permissions using the push REST API](search-index-access-control-lists-and-rbac-push-api.md), or you can use an indexer to automate data ingestion. This article focuses on the indexer approach.
19+
20+
The indexer approach is built on this foundation:
21+
22+
+ [Role-based access control (Azure RBAC)](/azure/storage/blobs/data-lake-storage-access-control-model#role-based-access-control-azure-rbac). There's no support for Attribute-based access control (Azure ABAC).
23+
24+
+ [An Azure AI Search indexer for Blob](search-howto-indexing-azure-blob-storage.md) that retrieves and ingests data and metadata, including permission filters. To get permission filter support, you must use the 2025-05-01-preview REST API or a prerelease package of an Azure SDK that supports the feature.
25+
26+
+ [An index in Azure AI Search](search-how-to-create-search-index.md) containing the ingested documents and corresponding permissions. Permission metadata is stored as fields in the index. To set up queries that respect the permission filters, you must use the 2025-05-01-preview REST API or a prerelease package of an Azure SDK that supports the feature.
27+
28+
## Prerequisites
29+
30+
+ [Microsoft Entra ID authentication and authorization](/entra/identity/authentication/overview-authentication). Services and apps must be in the same tenant. Role assignments are used for each authenticated connection.
31+
32+
+ Azure AI Search, any region, but you must have a billable tier (basic and higher) see [Service limits](search-limits-quotas-capacity.md) for managed identity support. The search service must be [configured for role-based access](search-security-enable-roles.md) and it must [have a managed identity (either system or user)](search-howto-managed-identities-data-sources.md).
33+
34+
## Limitations
35+
36+
+ The following indexer features don't support permission preservation capabilities but are otherwise operational for Azure Blob content-only indexing:
37+
+ One-to-many [parsing modes](/rest/api/searchservice/indexers/create?view=rest-searchservice-2025-05-01-preview&preserve-view=true#blobindexerparsingmode), such as: `delimitedText`, `jsonArray`, `jsonLines`, and `markdown` with sub-mode `oneToMany`
38+
39+
40+
### Authorization
41+
42+
For indexer execution, your search service identity must have **Storage Blob Data Reader** permission see [Connect to Azure Storage using a managed identity](search-howto-managed-identities-storage.md).
43+
44+
## Configure Azure AI Search for indexing permission filters
45+
46+
Recall that the search service must have:
47+
48+
+ [Role-based access enabled](search-security-enable-roles.md)
49+
+ [Managed identity configured](search-howto-managed-identities-data-sources.md)
50+
51+
### Authorization
52+
53+
For indexer execution, the client issuing the API call must have **Search Service Contributor** permission to create objects, **Search Index Data Contributor** permission to perform data import, and **Search Index Data Reader** to query an index see [Connect to Azure AI Search using roles](search-security-rbac.md).
54+
55+
## Indexing permission metadata
56+
57+
In Azure AI Search, configure an indexer, data source, and index to pull permission metadata from blobs.
58+
59+
### Configure the data source
60+
61+
+ Data Source type must be `azureblob`.
62+
63+
+ Data source must have `indexerPermissionOptions` with `rbacScope`.
64+
65+
+ For `rbacScope`, configure the [connection string](search-howto-index-azure-data-lake-storage.md#supported-credentials-and-connection-strings) with managed identity format.
66+
67+
+ For connection strings using a [user-assigned managed identity](search-howto-managed-identities-storage.md#user-assigned-managed-identity), you must also specify the `identity` property.
68+
69+
<!-- Question/Comment: check this example -->
70+
JSON example with system managed identity:
71+
72+
```json
73+
{
74+
"name" : "my-blob-datasource",
75+
"type": "azureblob",
76+
"indexerPermissionOptions": ["rbacScope"],
77+
"credentials": {
78+
"connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
79+
},
80+
"container": {
81+
"name": "<your container name>",
82+
"query": "<optional-query>"
83+
}
84+
}
85+
```
86+
87+
JSON schema example with a user-managed identity in the connection string:
88+
89+
```json
90+
{
91+
"name" : "my-blob-datasource",
92+
"type": "azureblob",
93+
"indexerPermissionOptions": ["rbacScope"],
94+
"credentials": {
95+
"connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
96+
},
97+
"container": {
98+
"name": "<your container name>",
99+
"query": "<optional-query>"
100+
},
101+
"identity": {
102+
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
103+
"userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
104+
}
105+
}
106+
```
107+
108+
### Create permission fields in the index
109+
110+
In Azure AI Search, make sure your index contains field definitions for the permission metadata. Permission metadata can be indexed when `indexerPermissionOptions` is specified in the data source definition.
111+
112+
Recommended schema attributes RBAC Scope:
113+
114+
+ RBAC scope field with `rbacScope` permissionFilter value.
115+
+ Property `permissionFilterOption` to enable filtering at querying time.
116+
+ Use string fields for permission metadata
117+
+ Set `filterable` to true on all fields.
118+
119+
Notice that `retrievable` is false. You can set it true during development to verify permissions are present, but remember to set to back to false before deploying to a production environment.
120+
121+
JSON schema example:
122+
123+
```json
124+
{
125+
...
126+
"fields": [
127+
...
128+
{
129+
"name": "RbacScope",
130+
"type": "Edm.String",
131+
"permissionFilter": "rbacScope",
132+
"filterable": true,
133+
"retrievable": false
134+
}
135+
],
136+
"permissionFilterOption": "enabled"
137+
}
138+
```
139+
140+
### Configure the indexer
141+
142+
Field mappings within an indexer set the data path to fields in an index. Target and destination fields that vary by name or data type require an explicit field mapping. The following metadata fields in Azure Blob might need field mappings if you vary the field name:
143+
144+
+ **metadata_rbac_scope** (`Edm.String`) - the container RBAC scope.
145+
146+
Specify `fieldMappings` in the indexer to route the permission metadata to target fields during indexing.
147+
148+
JSON schema example:
149+
150+
```json
151+
{
152+
...
153+
"fieldMappings": [
154+
{ "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
155+
]
156+
}
157+
```
158+
159+
## Deletion tracking
160+
161+
To effectively manage blob deletion, ensure that you have enabled [deletion tracking](search-howto-index-changed-deleted-blobs.md) before your indexer runs for the first time. This feature allows the system to detect deleted blobs from your source and have them deleted from the index.
162+

‎articles/search/search-howto-indexing-azure-blob-storage.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ To configure and run the indexer, you can use:
2727

2828
This article uses the REST APIs to illustrate each step.
2929

30+
> [!NOTE]
31+
> Azure AI Search can now ingest RBAC scope during indexing and transfers those permissions to indexed content in the search index. For more information about RBAC scope during indexing, see [Indexing Azure Role-Based Access Control scope using Indexers](search-blob-indexer-role-based-access.md).
32+
3033
## Prerequisites
3134

3235
+ [Azure Blob Storage](/azure/storage/blobs/storage-blobs-overview), Standard performance (general-purpose v2).

‎articles/search/toc.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -529,12 +529,14 @@ items:
529529
href: search-document-level-access-overview.md
530530
- name: Use security filters
531531
href: search-security-trimming-for-azure-search.md
532-
- name: Use ACLs
532+
- name: Use ACLs or RBAC scopes
533533
items:
534534
- name: Push document-level permissions to an index
535535
href: search-index-access-control-lists-and-rbac-push-api.md
536536
- name: Pull ADLS Gen2 permissions into an index
537537
href: search-indexer-access-control-lists-and-role-based-access.md
538+
- name: Pull Blob RBAC scopes into an index
539+
href: search-blob-indexer-role-based-access.md
538540
- name: Query with permission filters
539541
href: search-query-access-control-rbac-enforcement.md
540542
- name: Data encryption

0 commit comments

Comments
 (0)