Connect to Azure AI Search using Azure role-based access control (Azure RBAC)

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

In Azure AI Search, "control plane" refers to operations supported in the Management REST API or equivalent client libraries. The "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, synonym maps, indexers, data sources, and skillsets). See Microsoft.Search/searchServices/* for the permissions list. This role can't access content in an index, so no querying or indexing, but it can create, delete, and list indexes, return index definitions and statistics, and test analyzers. This role is for search service administrators who need to manage the search service and its objects, but without content access.
Search Index Data Contributor Data Read-write access to content in all indexes on the search service. This role is for developers or index owners who need to import, refresh, or query the documents collection of an index.
Search Index Data Reader Data Read-only access to all search indexes on the search service. This role is for apps and users who run queries.

Note

If you disable Azure role-based access, built-in roles for the control plane (Owner, Contributor, Reader) continue to be available. Disabling Azure RBAC removes just the data-related permissions associated with those roles. In a disabled-RBAC scenario, 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:

    • Contributors can view and create any object, but can't query an index using Search Explorer.

    • Search Index Data Readers can use Search Explorer to query the index. You can use any API version to check for access. You should be able to send queries and view results, but you shouldn't be able to view the index definition.

    • Search Index Data Contributors can select New Index to create a new index. Saving a new index verifies write access on the service.

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://graph.chinacloudapi.cn/"
    
  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 may want to limit 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 -Environment AzureChinaCloud
    
  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/a5b1ca8b-bab3-4c26-aebe-4cf7ec4791a0/resourceGroups/heidist-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

API keys can't be deleted, but they 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.

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

Conditional Access is a tool in Microsoft Entra ID used to enforce organizational policies. By using Conditional Access policies, you can apply the right access controls when needed to keep your organization secure. When accessing an Azure AI Search service using role-based access control, Conditional Access can enforce organizational policies.

To enable a Conditional Access policy for Azure AI Search, follow the below 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.