Enable or disable role-based access control in Azure AI Search

If you want to use Azure role-based access control for connections into Azure AI Search, this article explains how to enable it for your search service.

Role-based access for data plane operations is optional, but recommended. The alternative is key-based authentication, which is the default.

Roles for service administration (control plane) are built in and can't be enabled or disabled.

Note

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 Azure SDK client libraries.

Prerequisites

• Owner, User Access Administrator, or a custom role with Microsoft.Authorization/roleAssignments/write permissions.

• A search service in any region, on any tier, including free.

Enable role-based access for data plane operations

When you enable roles for the data plane, the change is effective immediately, but wait a few seconds before assigning roles.

The default failure mode is http401WithBearerChallenge. Alternatively, you can set the failure mode to http403.

Once role-based access is enabled, the search service recognizes an authorization header on data plane requests that provide an OAuth2 access token.

Azure portal

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

2. Select Settings and then select Keys in the left navigation pane.

   

3. Choose Role-based control or Both if you're currently using keys and need time to transition clients to role-based access control.

   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.

4. As an administrator, if you choose a roles-only approach, assign data plane roles to your user account to restore full administrative access over data plane operations in the Azure portal. Roles include Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader. You need all three roles if you want equivalent access.

   Sometimes it can take five to ten minutes for role assignments to take effect. Until that happens, the following message appears in the portal pages used for data plane operations.

   

Azure CLI

Run this script to support roles only:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Or, run this script to support both keys and roles:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

For more information, see Manage your Azure AI Search service with the Azure CLI.

Azure PowerShell

Run this command to set the authentication type to roles only:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Or, run this command to support both keys and roles:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

For more information, see Manage your Azure AI Search service with PowerShell.

REST API

Use the Management REST API Create or Update Service to configure your service for role-based access control.

All calls to the Management REST API are authenticated through Microsoft Entra ID. For help with setting up authenticated requests, see Manage Azure AI Search using REST.

1. Get service settings so that you can review the current configuration.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Use PATCH to update service configuration. The following modifications enable both keys and role-based access. If you want a roles-only configuration, see Disable API keys.

   Under "properties", set "authOptions" to "aadOrApiKey". The "disableLocalAuth" property must be false to set "authOptions".

   Optionally, set "aadAuthFailureMode" to specify whether 401 is returned instead of 403 when authentication fails. Valid values are "http401WithBearerChallenge" or "http403".

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

Disable role-based access control

It's possible to disable role-based access control for data plane operations and use key-based authentication instead. You might do this as part of a test workflow, for example to rule out permission issues.

Reverse the steps you followed previously to enable role-based access.

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

2. Select Settings and then select Keys in the left navigation pane.

3. Select API Keys.

Disable API key authentication

Key access, or local authentication, can be disabled on your service if you're exclusively 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.

Admin API keys can be disabled, but not deleted. Query API keys can be deleted.

Owner or Contributor permissions are required to disable security features.

Azure portal

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 coadministrator, you can use portal features to test role-based access.

Azure CLI

To disable key-based authentication, set -disableLocalAuth to true. This is the same syntax as the "enable roles only" script presented in the previous section.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

To re-enable key authentication, set -disableLocalAuth to false. The search service resumes acceptance of API keys on the request automatically (assuming they're specified).

For more information, see Manage your Azure AI Search service with the Azure CLI.

Azure PowerShell

To disable key-based authentication, set DisableLocalAuth to true. This is the same syntax as the "enable roles only" script presented in the previous section.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

To re-enable key authentication, set DisableLocalAuth to false. The search service resumes acceptance of API keys on the request automatically (assuming they're specified).

For more information, see Manage your Azure AI Search service with PowerShell.

REST API

To disable key-based authentication, set "disableLocalAuth" to true.

1. Get service settings so that you can review the current configuration.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Use PATCH to update service configuration. The following modification sets "authOptions" to null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

To re-enable key authentication, set "disableLocalAuth" to false. The search service resumes acceptance of API keys on the request automatically (assuming they're specified).

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.

---

Next steps

Set up roles for access to a search service