Connect to Azure AI Search using roles

Azure AI Search supports role-based access control through Microsoft Entra ID. Role-based access is optional but recommended. The alternative is key-based authentication, which is the default.

If you assign multiple roles to a security principal, permissions are combined. Role assignments apply across all tools and client libraries. You can assign roles using any supported approach.

This article explains how to assign built-in roles for service administration, development, and read-only query and retrieval access. It also provides steps for creating custom roles and testing role assignments.

Tip

Want a quick overview of the built-in roles? See Summary of permissions.
To control access to search results at the document level, also known as row-level security, see Document-level access control in Azure AI Search.

Prerequisites

An Azure AI Search service (any region and any tier) with role-based access enabled.
Permission to assign Azure roles. Any of the following roles work:
- Owner
- User Access Administrator
- Role Based Access Control Administrator
- A custom role with Microsoft.Authorization/roleAssignments/write permissions

Built-in roles

Roles are a collection of permissions that affect the control plane or data plane:

Control plane: Operations for service provisioning, configuration, and administration. Control plane operations include creating or deleting search services, listing API keys, and managing network and authentication settings. Available through the Azure Resource Manager REST APIs, Search Management REST APIs, and equivalent Azure SDK client libraries.
Data plane: Operations against the search service endpoint. Data plane operations fall into two categories: object management and content access. Available through the Search Service REST APIs and equivalent Azure SDK client libraries.

Role descriptions

The following built-in roles grant permissions to Azure AI Search. Control plane roles are always available, while data plane roles require role-based access to be enabled on your search service. You can combine built-in roles for broader access or create a custom role with the specific permissions you need.

Role	Plane	Description
Owner	Control	Full control plane access, including the ability to assign roles and change authentication settings. Subscription administrators have this role by default. Can manage API keys. Can't create search objects, load documents, query indexes, or retrieve from knowledge bases.
Contributor	Control	Same level of control plane access as Owner, minus the ability to assign roles.
Reader	Control	Read-only control plane access. Can view service metrics and object definitions. Can't view or manage API keys, load documents, query indexes, or retrieve from knowledge bases.
Search Service Contributor	Control & Data	Full control plane access. Data plane access is limited to object management. Can create indexes, indexers, skillsets, knowledge bases, and other search objects. Can't load documents, query indexes, or retrieve from knowledge bases. For the full permissions list, see `Microsoft.Search/searchServices/*`.
Search Index Data Contributor	Data	Read-write content access. Can load documents, query indexes, and retrieve from knowledge bases. Can't modify object definitions or retrieve admin keys.
Search Index Data Reader	Data	Read-only content access. Can query indexes and retrieve from knowledge bases. Can't load documents, modify object definitions, or retrieve admin keys.

Important

Owner, Contributor, and Search Service Contributor can retrieve admin keys, which provide full read-write access to the data plane. Only grant these roles to trusted users.
By default, data plane roles apply to all indexes on the search service. To scope Search Index Data Contributor or Search Index Data Reader to a single index, see Grant access to a single index.

Summary of permissions

Use the following table to quickly find which role provides the permissions you need.

Permissions	Owner/Contributor	Reader	Search Service Contributor	Search Index Data Contributor	Search Index Data Reader
Create and configure Azure AI Search services	✅	❌	✅	❌	❌
Access service in the Azure portal	✅	✅	✅	❌	❌
View service properties, metrics, and endpoint	✅	✅	✅	❌	❌
List all objects on the service	✅	✅	✅	❌	❌
Access quotas and service statistics	✅	❌	✅	❌	❌
View, copy, and regenerate keys	✅	❌	✅	❌	❌
Set authentication options	✅	❌	✅	❌	❌
View roles, policies, and definitions	✅	✅	✅	❌	❌
Configure network security and private connections	✅	❌	✅	❌	❌
Create, run, and manage search objects ¹	❌	❌	✅	❌	❌
Upload data for indexing ²	❌	❌	❌	✅	❌
Query an index	❌	❌	❌	✅	✅
Retrieve from a knowledge base	❌	❌	❌	✅	✅
Bypass permission filters with elevated read	❌	❌	❌	✅	❌

¹ Includes indexes, indexers, data sources, skillsets, aliases, synonym maps, debug sessions, knowledge bases, and knowledge sources. Indexers also support run and reset operations.

² An Owner or Contributor can run the Import data wizard to create and load indexes, even though they can't upload documents in other clients. Similarly, indexers can write to any index on the search service, regardless of per-index role assignments. In both cases, the search service (not the user) performs the data plane actions using its Microsoft.Search/searchServices/indexes/documents/* permissions.

Assign built-in roles

In this section, you assign roles for:

Service administration
Development
Read-only access

Assign roles for service administration

The following roles let you create, configure, and manage a search service. These roles are hierarchical, so select one based on the access level you need.

Role	ID
Owner	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Reader	acdd72a7-3385-48ef-bd42-f606fba81ae7

Azure portal
PowerShell

Go to your search service in the Azure portal.
From the left pane, select Access control (IAM).
Select + Add > Add role assignment.
Select a role: Owner, Contributor, or Reader.
On the Members tab, select the Microsoft Entra user or group identity. If you're setting up permissions for another Azure service, select a system-assigned or user-assigned managed identity.
On the Review + assign tab, select Review + assign to assign the role.

When you assign roles using PowerShell, call New-AzRoleAssignment, providing the Azure user or group name and the scope of the assignment.

This example creates a role assignment scoped to a search service:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Reference: New-AzRoleAssignment

Assign roles for development

The following roles let you create search objects, load documents, query indexes, and retrieve from knowledge bases. Assign all three roles to cover the full range of development tasks.

Role	ID
Search Service Contributor	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Search Index Data Contributor	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Search Index Data Reader	1407120a-92aa-4202-b7e9-c0e197c71c8f

Azure portal
PowerShell

Go to your search service in the Azure portal.
From the left pane, select Access control (IAM).
Select + Add > Add role assignment.
Select Search Service Contributor.
On the Members tab, select the Microsoft Entra user or group identity. If you're setting up permissions for another Azure service, select a system-assigned or user-assigned managed identity.
On the Review + assign tab, select Review + assign to assign the role.
Repeat these steps to assign Search Index Data Contributor and Search Index Data Reader.

When you assign roles using PowerShell, call New-AzRoleAssignment, providing the Azure user or group name and the scope of the assignment.

This example creates a role assignment scoped to a search service:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

This example creates a role assignment scoped to a specific index:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Reference: New-AzRoleAssignment

Assign roles for read-only access

Use the following role for apps and processes that only need read access to indexes and knowledge bases. Supported operations include search, lookup, autocomplete, and suggestions for indexes and retrieve for knowledge bases.

Role	ID
Search Index Data Reader	1407120a-92aa-4202-b7e9-c0e197c71c8f

Azure portal
PowerShell

Go to your search service in the Azure portal.
From the left pane, select Access control (IAM).
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 Azure service, select a system-assigned or user-assigned managed identity.
On the Review + assign tab, select Review + assign to assign the role.

When you assign roles using PowerShell, call New-AzRoleAssignment, providing the Azure user or group name and the scope of the assignment.

Get your subscription ID, search service resource group, and search service name.
Get the object identifier of your Azure service, such as Azure OpenAI.
```
 Get-AzADServicePrincipal -SearchString <your-azure-openai-resource-name>
```
The output includes an Id property containing the object ID you need for the role assignment.
Get the role definition and review the permissions to make sure this is the role you want.
```
Get-AzRoleDefinition -Name "Search Index Data Reader"
```

Create the role assignment, substituting valid values for the placeholders.

New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>

A successful assignment returns the role assignment details including RoleAssignmentId.

Here's an example of a role assignment scoped to a specific index:

New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>/indexes/<your-index-name>

Reference: New-AzRoleAssignment

Test role assignments

Use a client to test role assignments. Remember that roles are cumulative. You can't delete or deny inherited roles that are scoped to the subscription or resource group level at the resource (search service) level.

Before you proceed, configure your application for keyless connections and have role assignments in place.

Go to your search service in the Azure portal.
From the left pane, select Search management > Indexes to test index-related permissions:
- Search Service Contributors can create, modify, and delete search objects but can't load documents or run queries. To verify permissions, create a search index.
- Search Index Data Contributors can load documents. There's no load documents option in the Azure portal outside of the Import data wizard, but you can reset and run an indexer to confirm document load permissions.
- Search Index Data Readers can query indexes. To verify permissions, use Search explorer. You should be able to send queries and view results, but you shouldn't be able to view index definitions or create indexes.

This approach assumes Visual Studio Code with the REST Client extension.

Open a command shell for Azure CLI and sign in to your Azure subscription.
```
az login
```
Get your tenant ID and subscription ID. Use the ID as a variable in a future step.
```
az account show
```

Get an access token for the Azure AI Search data plane.

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Paste these variables in 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

Send a request that uses the variables you specify. For the Search Index Data Reader role, you can send a query using any supported API version.
```
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2025-09-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }
```
Reference: Search Documents

A successful query returns search results with matching documents. If the index is empty or has no matches, value contains an empty array.

Tip

For more information on how to acquire a token for a specific environment, see Manage an Azure AI Search service with REST APIs and Microsoft identity platform authentication libraries.

Install the required packages:

dotnet add package Azure.Search.Documents
dotnet add package Azure.Identity

Use Azure.Identity for .NET for token authentication. Microsoft recommends DefaultAzureCredential() for most scenarios.

Here's an example of a client connection using DefaultAzureCredential():

// Create a SearchIndexClient to send create/delete index commands
// Requires Search Service Contributor role
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());

// Create a SearchClient to load and query documents
// Requires Search Index Data Contributor (load) or Search Index Data Reader (query)
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

Reference: SearchClient, SearchIndexClient, DefaultAzureCredential

Here's another example of using client secret credential:

var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);

Here's an example of running a query:

SearchResults<SearchDocument> response = srchclient.Search<SearchDocument>("motel");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    Console.WriteLine(result.Document["HotelName"]);
}

A successful query returns search results. If no documents match, the results collection is empty.

Install the required packages:

pip install azure-search-documents azure-identity

Use Azure.Identity for Python for token authentication.
Use DefaultAzureCredential if the Python client is an application that executes server-side. Enable interactive authentication if the app runs in a browser.

Here's an example:

from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
endpoint = "https://<mysearch>.search.windows.net"
index_name = "myindex"
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

Reference: SearchClient, DefaultAzureCredential

Install the required packages:

npm install @azure/search-documents @azure/identity

Use Azure.Identity for JavaScript for token authentication.
If you're using React, use InteractiveBrowserCredential for Microsoft Entra authentication to Azure AI Search. For more information, see When to use @azure/identity.

Reference: SearchClient, DefaultAzureCredential

Add the required dependencies to your pom.xml:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-search-documents</artifactId>
  <version>11.7.4</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
  <version>1.15.0</version>
</dependency>

Use Azure.Identity for Java for token authentication.
Use DefaultAzureCredential for apps that run on Azure.

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 Azure portal doesn't currently support role assignments at this level of granularity, but you can assign roles using 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 Azure and AzureAD modules and connect to your Azure account:

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

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

Reference: New-AzRoleAssignment

Per-index scope and indexer operations

Per-index role assignments apply to direct API operations only, such as queries or document uploads from users or applications. Indexers aren't restricted by per-index permissions because they operate with service-level credentials.

A user with the Search Service Contributor role can create indexers that write to any index on the search service, even indexes where that user has no per-index role assignment.

For strict data isolation between indexes, consider these approaches:

Use separate search services for teams or users who require index-level isolation.
Assign Search Service Contributor only to administrators who manage indexers.
Use document-level access control with security filters to restrict query results within a shared index.

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.

The following examples clone Search Index Data Reader and then add the ability to list indexes by name. Normally, listing the indexes on a search service is considered an administrative right.

Sign in to the Azure portal and navigate to your search service.
From the left pane, select Access control (IAM).
On the Roles tab, find Search Index Data Reader or another role, select the ellipsis (...), and then select Clone.
On the Basics tab, enter a name for the custom role, such as "Search Index Data Explorer", and then select Next.
On the Permissions tab, select Add permissions.
In the Add permissions pane, select the Microsoft Search tile.
With Actions selected at the top, set the following permissions:
- Under Microsoft.Search/operations, select Read : List all available operations.
- Under Microsoft.Search/searchServices/indexes, select Read : Read Index.

Switch to Data Actions at the top, 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 Add to close the pane.
Select Review + create to create the role.

You can now assign users and groups to the role. For more information about these steps, see Create or update Azure custom roles using the Azure portal.

The PowerShell example shows the JSON syntax for creating a custom role that's a clone of Search Index Data Reader, but with the ability to list all indexes by name.

Review the list of atomic permissions to determine which ones you need. For this example, you need the following permissions:

"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/read",
"Microsoft.Search/searchServices/indexes/read"

Set up a PowerShell session to create the custom role. For detailed instructions, see Azure PowerShell.

Provide the role definition as a JSON document. The following example shows the syntax for creating a custom role with PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Note

If you assign the scope at the index level, use the data action "Microsoft.Search/searchServices/indexes/documents/read".

Create a Conditional Access policy

If you need to enforce organizational policies, such as multifactor authentication, use Microsoft Entra Conditional Access.

To create a Conditional Access policy for Azure AI Search:

Sign in to the Azure portal.
Search for Microsoft Entra Conditional Access.
On the Overview page, select Create new policy.
Under Cloud apps or actions, add Azure AI Search as a cloud app, depending on how you want to set up your policy.
Update the remaining parameters of your policy. For example, specify which users and groups to which the policy applies.
Save the policy.

Important

If your search service has a managed identity assigned to it, the specific search service appears as a cloud app. However, selecting that specific search service doesn't enforce the policy. Instead, select the general Azure AI Search cloud app to apply Conditional Access policies to your search service.

Troubleshooting

When you develop applications that use role-based access control for authentication, you might encounter some common problems:

The default configuration for a search service is key-based authentication. If you don't change this setting to Both or Role-based access control, all requests that use role-based authentication are automatically denied, regardless of the underlying permissions.
If your request includes an API key alongside role-based credentials, the service authenticates using the key. Remove the API key from your request headers to use role-based authentication.
If the authorization token comes from a managed identity and you recently assigned the appropriate permissions, it might take several hours for the permissions assignments to take effect.
If queries with document-level permissions don't return expected results, use Search Index Data Contributor or create a custom role with elevated permissions to investigate.

Next step

This article explains how to assign roles for control and data plane operations on Azure AI Search. For comprehensive instructions on adding role-based access to your application code:

Connect your app to Azure AI Search using identities

Feedback

Was this page helpful?

Last updated on 2026-04-07

Share via

Connect to Azure AI Search using roles

Prerequisites

Built-in roles

Role descriptions

Summary of permissions

Assign built-in roles

Assign roles for service administration

Assign roles for development

Assign roles for read-only access

Test role assignments

Grant access to a single index

Per-index scope and indexer operations

Create a custom role

Create a Conditional Access policy

Troubleshooting

Next step

Feedback

Additional resources