Connect to Azure AI Search using roles

  • Article

Azure provides a global authentication and role-based 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

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.

Combine these roles to get sufficient permissions for your use case.

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.

  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.

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

  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.

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.

Another combination of roles that provides full access is Contributor or Owner, plus Search Index Data Reader.

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.

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

  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.

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

This section provides basic steps for setting up the role assignment and is here for completeness, but we recommend Use Azure AI Search without keys for comprehensive instructions on configuring your app for role-based access.

  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.

  5. Select the Search Index Data Reader role.

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

  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 level can't be deleted or denied at the resource (search service) level.

Configure your application for keyless connections and have role assignments in place before testing.

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

  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. Paste these variables into a new text file in Visual Studio Code.

    @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=2024-07-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 -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/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.

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.

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.

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.