Connect to Azure AI Search using role-based access controls
Azure provides a global role-based access control authorization system for all services running on the platform. In Azure AI Search, you can assign Azure roles for:
Per-user access over search results (sometimes referred to as row-level security or document-level security) isn't supported through role assignments. As a workaround, create security filters that trim results by user identity, removing documents for which the requestor shouldn't have access. See this Enterprise chat sample using RAG for a demonstration.
Role assignments are cumulative and pervasive across all tools and client libraries. You can assign roles using any of the supported approaches described in Azure role-based access control documentation.
Role-based access is optional, but recommended. The alternative is key-based authentication, which is the default.
Prerequisites
Owner, User Access Administrator, or a role with Microsoft.Authorization/roleAssignments/write permissions.
A search service in any region, on any tier.
Limitations
Role-based access control can increase the latency of some requests. Each unique combination of service resource (index, indexer, etc.) and service principal triggers an authorization check. These authorization checks can add up to 200 milliseconds of latency per request.
In rare cases where requests originate from a high number of different service principals, all targeting different service resources (indexes, indexers, etc.), it's possible for the authorization checks to result in throttling. Throttling would only happen if hundreds of unique combinations of search service resource and service principal were used within a second.
Enable role-based access for data plane operations
Roles for service administration (control plane) is mandatory. Roles for data plane operations are optional. You must enable role-based access before you can assign Search Service Contributor, Search Index Data Contributor, or Search Index Data Reader roles for data operations.
In this step, configure your search service to recognize an authorization header on data plane requests that provide an OAuth2 access token.
Data plane refers to operations against the search service endpoint, such as indexing or queries, or any other operation specified in the Search REST API or equivalent client libraries.
Sign in to the Azure portal and open the search service page.
Select Keys in the left navigation pane.
Choose Role-based control or Both if you want flexibility.
Option Description API Key (default). Requires API keys on the request header for authorization. Role-based access control Requires membership in a role assignment to complete the task. It also requires an authorization header on the request. Both Requests are valid using either an API key or role-based access control, but if you provide both in the same request, the API key is used.
The change is effective immediately, but wait a few seconds before assigning roles.
When you enable role-based access control, the failure mode is "http401WithBearerChallenge" if authorization fails.
Built-in roles used in Azure AI Search
The following roles are built in. If these roles are insufficient, create a custom role.
| Role | Plane | Description |
|---|---|---|
| Owner | Control & Data | Full access to the control plane of the search resource, including the ability to assign Azure roles. Only the Owner role can enable or disable authentication options or manage roles for other users. Subscription administrators are members by default. On the data plane, this role has the same access as the Search Service Contributor role. It includes access to all data plane actions except the ability to query or index documents. |
| Contributor | Control & Data | Same level of control plane access as Owner, minus the ability to assign roles or change authentication options. On the data plane, this role has the same access as the Search Service Contributor role. It includes access to all data plane actions except the ability to query or index documents. |
| Reader | Control & Data | Read access across the entire service, including search metrics, content metrics (storage consumed, number of objects), and the object definitions of data plane resources (indexes, indexers, and so on). However, it can't read API keys or read content within indexes. |
| Search Service Contributor | Control & Data | Read-write access to object definitions (indexes, aliases, synonym maps, indexers, data sources, and skillsets). This role is for developers who create objects, and for administrators who manage a search service and its objects, but without access to index content. Use this role to create, delete, and list indexes, get index definitions, get service information (statistics and quotas), test analyzers, create and manage synonym maps, indexers, data sources, and skillsets. See Microsoft.Search/searchServices/* for the permissions list. |
| Search Index Data Contributor | Data | Read-write access to content in indexes. This role is for developers or index owners who need to import, refresh, or query the documents collection of an index. This role doesn't support index creation or management. By default, this role is for all indexes on a search service. See Grant access to a single index to narrow the scope. |
| Search Index Data Reader | Data | Read-only access for querying search indexes. This role is for apps and users who run queries. This role doesn't support read access to object definitions. For example, you can't read a search index definition or get search service statistics. By default, this role is for all indexes on a search service. See Grant access to a single index to narrow the scope. |
Note
If you disable Azure role-based access, built-in roles for the control plane (Owner, Contributor, Reader) continue to be available. Disabling role-based access removes just the data-related permissions associated with those roles. If data plane roles are disabled, Search Service Contributor is equivalent to control-plane Contributor.
Assign roles
In this section, assign roles for:
Assign roles for service administration
As a service administrator, you can create and configure a search service, and perform all control plane operations described in the Management REST API or equivalent client libraries. Depending on the role, you can also perform most data plane Search REST API tasks.
Sign in to the Azure portal.
Navigate to your search service.
Select Access Control (IAM) in the left navigation pane.
Select + Add > Add role assignment.
Select an applicable role:
- Owner (full access to all data plane and control plane operations, except for query permissions)
- Contributor (same as Owner, except for permissions to assign roles)
- Reader (acceptable for monitoring and viewing metrics)
On the Members tab, select the Microsoft Entra user or group identity.
On the Review + assign tab, select Review + assign to assign the role.
Assign roles for development
Role assignments are global across the search service. To scope permissions to a single index, use PowerShell or the Azure CLI to create a custom role.
Important
If you configure role-based access for a service or index and you also provide an API key on the request, the search service uses the API key to authenticate.
Sign in to the Azure portal.
Navigate to your search service.
Select Access Control (IAM) in the left navigation pane.
Select + Add > Add role assignment.
Select a role:
- Search Service Contributor (create-read-update-delete operations on indexes, indexers, skillsets, and other top-level objects)
- Search Index Data Contributor (load documents and run indexing jobs)
- Search Index Data Reader (query an index)
Another combination of roles that provides full access is Contributor or Owner, plus Search Index Data Reader.
On the Members tab, select the Microsoft Entra user or group identity.
On the Review + assign tab, select Review + assign to assign the role.
Repeat for the other roles. Most developers need all three.
Assign roles for read-only queries
Use the Search Index Data Reader role for apps and processes that only need read-access to an index. This is a very specific role. It grants GET or POST access to the documents collection of a search index for search, autocomplete, and suggestions.
It doesn't support GET or LIST operations on an index or other top-level objects, or GET service statistics.
Sign in to the Azure portal.
Navigate to your search service.
Select Access Control (IAM) in the left navigation pane.
Select + Add > Add role assignment.
Select the Search Index Data Reader role.
On the Members tab, select the Microsoft Entra user or group identity. If you're setting up permissions for another service, you might be using a system or user-managed identity. Choose that option if the role assignment is for a service identity.
On the Review + assign tab, select Review + assign to assign the role.
Test role assignments
Use a client to test role assignments. Remember that roles are cumulative and inherited roles that are scoped to the subscription or resource group level can't be deleted or denied at the resource (search service) level.
Make sure that you register your client application with Microsoft Entra ID and have role assignments in place before testing access.
Sign in to the Azure portal.
Navigate to your search service.
On the Overview page, select the Indexes tab:
Search Service Contributors can view and create any object, but can't load documents or query an index. To verify permissions, create a search index.
Search Index Data Contributors can load documents. There's no load documents option in the portal outside of Import data wizard, but you can reset and run an indexer to confirm document load permissions.
Search Index Data Readers can query the index. To verify permissions, use Search explorer. You should be able to send queries and view results, but you shouldn't be able to view the index definition or create one.
Test as current user
If you're already a Contributor or Owner of your search service, you can present a bearer token for your user identity for authentication to Azure AI Search.
Get a bearer token for the current user using the Azure CLI:
az account get-access-token --scope https://search.azure.com/.defaultOr by using PowerShell:
Get-AzAccessToken -ResourceUrl https://search.azure.comIn a new text file in Visual Studio Code, paste in these variables:
@baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE @index-name = PASTE-YOUR-INDEX-NAME-HERE @token = PASTE-YOUR-TOKEN-HEREPaste in and then send a request to confirm access. Here's one that queries the hotels-quickstart index
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} { "queryType": "simple", "search": "motel", "filter": "", "select": "HotelName,Description,Category,Tags", "count": true }
Grant access to a single index
In some scenarios, you might want to limit an application's access to a single resource, such as an index.
The portal doesn't currently support role assignments at this level of granularity, but it can be done with PowerShell or the Azure CLI.
In PowerShell, use New-AzRoleAssignment, providing the Azure user or group name, and the scope of the assignment.
Load the
AzureandAzureADmodules and connect to your Azure account:Import-Module -Name Az Import-Module -Name AzureAD Connect-AzAccountAdd a role assignment scoped to an individual index:
New-AzRoleAssignment -ObjectId <objectId> ` -RoleDefinitionName "Search Index Data Contributor" ` -Scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
Create a custom role
If built-in roles don't provide the right combination of permissions, you can create a custom role to support the operations you require.
This example clones Search Index Data Reader and then adds the ability to list indexes by name. Normally, listing the indexes on a search service is considered an administrative right.
These steps are derived from Create or update Azure custom roles using the Azure portal. Cloning from an existing role is supported in a search service page.
These steps create a custom role that augments search query rights to include listing indexes by name. Typically, listing indexes is considered an admin function.
In the Azure portal, navigate to your search service.
In the left-navigation pane, select Access Control (IAM).
In the action bar, select Roles.
Right-click Search Index Data Reader (or another role) and select Clone to open the Create a custom role wizard.
On the Basics tab, provide a name for the custom role, such as "Search Index Data Explorer", and then select Next.
On the Permissions tab, select Add permission.
On the Add permissions tab, search for and then select the Microsoft Search tile.
Set the permissions for your custom role. At the top of the page, using the default Actions selection:
- Under Microsoft.Search/operations, select Read : List all available operations.
- Under Microsoft.Search/searchServices/indexes, select Read : Read Index.
On the same page, switch to Data actions and under Microsoft.Search/searchServices/indexes/documents, select Read : Read Documents.
The JSON definition looks like the following example:
{ "properties": { "roleName": "search index data explorer", "description": "", "assignableScopes": [ "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc" ], "permissions": [ { "actions": [ "Microsoft.Search/operations/read", "Microsoft.Search/searchServices/indexes/read" ], "notActions": [], "dataActions": [ "Microsoft.Search/searchServices/indexes/documents/read" ], "notDataActions": [] } ] } }Select Review + create to create the role. You can now assign users and groups to the role.
Disable API key authentication
Key access, or local authentication, can be disabled on your service if you're using the built-in roles and Microsoft Entra authentication. Disabling API keys causes the search service to refuse all data-related requests that pass an API key in the header.
Note
Admin API keys can only be disabled, not deleted. Query API keys can be deleted.
Owner or Contributor permissions are required to disable features.
To disable key-based authentication, use Azure portal or the Management REST API.
In the Azure portal, navigate to your search service.
In the left-navigation pane, select Keys.
Select Role-based access control.
The change is effective immediately, but wait a few seconds before testing. Assuming you have permission to assign roles as a member of Owner, service administrator, or coadministrator, you can use portal features to test role-based access.
Conditional Access
We recommend Microsoft Entra Conditional Access if you need to enforce organizational policies, such as multifactor authentication.
To enable a Conditional Access policy for Azure AI Search, follow these steps:
Sign in to the Azure portal.
Search for Microsoft Entra Conditional Access.
Select Policies.
Select New policy.
In the Cloud apps or actions section of the policy, add Azure AI Search as a cloud app depending on how you want to set up your policy.
Update the remaining parameters of the policy. For example, specify which users and groups this policy applies to.
Save the policy.
Important
If your search service has a managed identity assigned to it, the specific search service will show up as a cloud app that can be included or excluded as part of the Conditional Access policy. Conditional Access policies can't be enforced on a specific search service. Instead make sure you select the general Azure AI Search cloud app.
Troubleshooting role-based access control issues
When developing applications that use role-based access control for authentication, some common issues might occur:
If the authorization token came from a managed identity and the appropriate permissions were recently assigned, it might take several hours for these permissions assignments to take effect.
The default configuration for a search service is key-based authentication. If you didn't change the default key setting to Both or Role-based access control, then all requests using role-based authentication are automatically denied regardless of the underlying permissions.
Σχόλια
Σύντομα διαθέσιμα: Καθ' όλη τη διάρκεια του 2024 θα καταργήσουμε σταδιακά τα ζητήματα GitHub ως μηχανισμό ανάδρασης για το περιεχόμενο και θα το αντικαταστήσουμε με ένα νέο σύστημα ανάδρασης. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα: https://aka.ms/ContentUserFeedback.
Υποβολή και προβολή σχολίων για