Connect to Azure AI Search using roles

1. Sign in to the Azure portal.

2. Select Access Control (IAM) in the left pane.

3. Select + Add > Add role assignment to start the Add role assignment wizard.

   

4. Select a 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)

5. 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 or user-managed identity.

6. On the Review + assign tab, select Review + assign to assign the role.

When you use PowerShell to assign roles, 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

1. Sign in to the Azure portal.

2. Select Access Control (IAM) in the left pane.

3. Select + Add > Add role assignment to start the Add role assignment wizard.

   

4. Select a role.

   • Search Service Contributor (create, read, update, and 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)

5. 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 or user-managed identity.

6. On the Review + assign tab, select Review + assign to assign the role.

When you use PowerShell to assign roles, 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

1. Sign in to the Azure portal.

2. Select Access Control (IAM) in the left pane.

3. Select + Add > Add role assignment to start the Add role assignment wizard.

   

4. Select the Search Index Data Reader role.

5. 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 or user-managed identity.

6. On the Review + assign tab, select Review + assign to assign the role.

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

1. Get your subscription ID, search service resource group, and search service name.

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

3. Get the role definition and review the permissions to make sure this is the role you want.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

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

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

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

This approach assumes Visual Studio Code with a REST client extension.

1. Open a command shell for Azure CLI and sign in to your Azure subscription.

   az login
   

2. Get your tenant ID and subscription ID. Use the ID as a variable in a future step.

   az account show
   

3. Get an access token.

   az account get-access-token --query accessToken --output tsv
   

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

5. Paste and then send a request that uses the variables you specify. For the "Search Index Data Reader" role, you can send a query. You can use 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
        }
   

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

   Reference: Search Documents

1. Install the required packages:

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

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

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

4. Here's another example of using client secret credential:

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

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

1. Install the required packages:

   pip install azure-search-documents azure-identity
   

2. Use Azure.Identity for Python for token authentication.

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

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

1. Install the required packages:

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

2. Use Azure.Identity for JavaScript for token authentication.

3. If you're using React, use InteractiveBrowserCredential for Microsoft Entra authentication to Search. See When to use @azure/identity for details.

1. Add the required dependencies to your pom.xml:

   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-search-documents</artifactId>
     <version>11.6.0</version>
   </dependency>
   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-identity</artifactId>
     <version>1.10.0</version>
   </dependency>
   

2. Use Azure.Identity for Java for token authentication.

3. Use DefaultAzureCredential for apps that run on Azure.

These steps are derived from Create or update Azure custom roles using the Azure portal. A search service page supports cloning from an existing role.

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, go 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, use 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.

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.

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

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

3. 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}"
  ]
}

1. Review the list of atomic permissions to determine which ones you need.

2. See Create or update Azure custom roles using the REST API for steps.

3. Copy or create a role, or use JSON to specify the custom role (see the PowerShell tab for JSON syntax).

1. Review the list of atomic permissions to determine which ones you need.

2. See Create or update Azure custom roles using Azure CLI for steps.

3. See the PowerShell tab for JSON syntax.