Connect your app to Azure AI Search using identities

In your application code, you can set up a keyless connection to Azure AI Search that uses Microsoft Entra ID and roles for authentication and authorization. Application requests to most Azure services must be authenticated with keys or keyless connections. Developers must be diligent to never expose the keys in an unsecure location. Anyone who gains access to the key is able to authenticate to the service. Keyless authentication offers improved management and security benefits over the account key because there's no key (or connection string) to store.

This article explains how to use DefaultAzureCredential in your application code.

To implement keyless connections in your code, follow these steps:

• Enable role-based access on your search service
• Set environment variables, as needed.
• Use an Azure Identity library credential type to create an Azure AI Search client object.

Prerequisites

• Azure AI Search, any region but it must be a billable tier (basic or higher).

• Role-based access enabled on your search service.

• Role assignments on Azure AI Search. Assign these roles to your identity:

  • Search Service Contributor and Search Index Data Contributor for local development (full access)
  • Search Index Data Reader for production read-only queries

  For step-by-step instructions, see Assign roles for development.

Install Azure Identity client library

To use a keyless approach, update your AI Search enabled code with the Azure Identity client library.

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

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.15.1</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

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

pip install azure-identity azure-search-documents

Update source code to use DefaultAzureCredential

The Azure Identity library's DefaultAzureCredential allows you to run the same code in the local development environment and in the Azure cloud. Create a single credential and reuse the credential instance as needed to take advantage of token caching.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.azure.com"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index_name=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

Verify your connection

After setting up the client, verify your connection by running a simple operation. The following example lists indexes on your search service:

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

// List indexes to verify connection
searchIndexClient.listIndexNames().forEach(System.out::println);

// List indexes to verify connection
for await (const name of indexClient.listIndexesNames()) {
  console.log(name);
}

# List indexes to verify connection
for index in search_index_client.list_index_names():
    print(index)

A successful connection prints the names of your indexes (or an empty list if no indexes exist). If you receive an authentication error, verify that role-based access is enabled and your identity has the required role assignments.

The default authority is Azure public cloud. Custom audience values for sovereign or specialized clouds include:

• https://search.azure.us for Azure Government
• https://search.azure.cn for Azure operated by 21Vianet
• https://search.microsoftazure.de for Azure Germany

Local development

Local development using roles includes these steps:

• Assign your personal identity to RBAC roles on the specific resource.
• Use a tool like the Azure CLI or Azure PowerShell to authenticate with Azure.
• Establish environment variables for your resource.

Roles for local development

As a local developer, your Azure identity needs full control over data plane operations. These are the suggested roles:

• Search Service Contributor, create and manage objects
• Search Index Data Contributor, load and query an index

Find your personal identity with one of the following tools. Use that identity as the <identity-id> value.

Authentication for local development

Use a tool in your local development environment to authentication to Azure identity. Once you're authenticated, the DefaultAzureCredential instance in your source code finds and uses your identity for authentication purposes.

Select a tool for authentication during local development.

Configure environment variables for local development

To connect to Azure AI Search, your code needs to know your resource endpoint.

Create an environment variable named AZURE_SEARCH_ENDPOINT for your Azure AI Search endpoint. This URL generally has the format https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Production workloads

Deploy production workloads includes these steps:

• Choose RBAC roles that adhere to the principle of least privilege.
• Assign RBAC roles to your production identity on the specific resource.
• Set up environment variables for your resource.

Roles for production workloads

To create your production resources, you need to create a user-assigned managed identity then assign that identity to your resources with the correct roles.

The following role is suggested for a production application:

Authentication for production workloads

Use the following Azure AI Search Bicep template to create the resource and set the authentication for the identityId. Bicep requires the role ID. The name shown in this Bicep snippet isn't the Azure role; it's specific to the Bicep deployment.

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

The main.bicep file calls the following generic Bicep code to create any role. You have the option to create multiple RBAC roles, such as one for the user and another for production. This allows you to enable both development and production environments within the same Bicep deployment.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

Configure environment variables for production workloads

To connect to Azure AI Search, your code needs to know your resource endpoint, and the ID of the managed identity.

Create environment variables for your deployed and keyless Azure AI Search resource:

• AZURE_SEARCH_ENDPOINT: This URL is the access point for your Azure AI Search resource. This URL generally has the format https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: This is the identity to authenticate as.

Troubleshoot common errors

Related content

• Keyless connections developer guide
• Azure built-in roles
• Set environment variables