Edit

Connect to Azure AI Search using Azure role-based access control

  • Article

Azure provides a global role-based access control authorization system for all services running on the platform. In Azure AI Search, you can use Azure roles for:

  • Control plane operations (service administration tasks through Azure Resource Manager).

  • Data plane operations, such as creating, loading, and querying indexes.

Per-user access over search results (sometimes referred to as row-level security or document-level security) isn't supported. As a workaround, create security filters that trim results by user identity, removing documents for which the requestor shouldn't have access.

Note

A quick note about terminology. Control plane refers to operations supported in the Management REST API or equivalent client libraries. 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.

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.

Limitations

  • Adoption of role-based access control might increase the latency of some requests. Each unique combination of service resource (index, indexer, etc.) and service principal used on a request triggers an authorization check. These authorization checks can add up to 200 milliseconds of latency to a 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.

Configure role-based access for data plane

Applies to: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor

In this step, configure your search service to recognize an authorization header on data requests that provide an OAuth2 access token.

  1. Sign in to the Azure portal and open the search service page.

  2. Select Keys in the left navigation pane.

    Screenshot of the keys page with authentication options.

  3. Choose an API access control option. We recommend Both if you want flexibility or need to migrate apps.

    Option Description
    API Key (default). Requires an admin or query API keys on the request header for authorization. No roles are used.
    Role-based access control Requires membership in a role assignment to complete the task, described in the next step. It also requires an authorization header.
    Both Requests are valid using either an API key or role-based access control.

The change is effective immediately, but wait a few seconds before testing.

All network calls for search service operations and content respect the option you select: API keys, bearer token, or either one if you select Both.

When you enable role-based access control in the portal, the failure mode is "http401WithBearerChallenge" if authorization fails.

Assign roles

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.

You must be an Owner or have Microsoft.Authorization/roleAssignments/write permissions to manage role assignments.

Role assignments in the portal are service-wide. If you want to grant permissions to a single index, use PowerShell or the Azure CLI instead.

  1. Sign in to the Azure portal.

  2. Navigate to your search service.

  3. Select Access Control (IAM) in the left navigation pane.

  4. Select + Add > Add role assignment.

    Access control (IAM) page with Add role assignment menu open.

  5. Select an applicable role:

    • Owner
    • Contributor
    • Reader
    • Search Service Contributor
    • Search Index Data Contributor
    • Search Index Data Reader

  6. On the Members tab, select the Microsoft Entra user or group identity.

  7. 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 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.

  1. Sign in to the Azure portal.

  2. Navigate to your search service.

  3. 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 and query documents. To verify permissions, use Search explorer to query documents. There's no load documents option in the portal outside of Import data wizard. Because the wizard also creates objects, you would need Search Service Contributor, plus Search Index Data Contributor.

    • 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.

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.

  1. Get a bearer token for the current user using the Azure CLI:

    az account get-access-token --scope https://search.azure.com/.default

    Or by using PowerShell:

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. In 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-HERE

  3. Paste 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.

  1. Load the Azure and AzureAD modules and connect to your Azure account:

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. Add 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.

  1. In the Azure portal, navigate to your search service.

  2. In the left-navigation pane, select Access Control (IAM).

  3. In the action bar, select Roles.

  4. Right-click Search Index Data Reader (or another role) and select Clone to open the Create a custom role wizard.

  5. On the Basics tab, provide a name for the custom role, such as "Search Index Data Explorer", and then select Next.

  6. On the Permissions tab, select Add permission.

  7. On the Add permissions tab, search for and then select the Microsoft Search tile.

  8. 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.

  9. 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": []
         }
     ]
   }
 }

  10. 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 Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader 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.

  1. In the Azure portal, navigate to your search service.

  2. In the left-navigation pane, select Keys.

  3. 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 co-administrator, 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:

  1. Sign in to the Azure portal.

  2. Search for Microsoft Entra Conditional Access.

  3. Select Policies.

  4. Select New policy.

  5. 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.

  6. Update the remaining parameters of the policy. For example, specify which users and groups this policy applies to.

  7. 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 only. 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.