Use Azure AI Search without keys

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.

Keyless connections are enabled with the following steps:

• Configure your authentication.
• Set environment variables, as needed.
• Use an Azure Identity library credential type to create an Azure AI Search client object.

Prerequisites

The following steps need to be completed for both local development and production workloads:

• Create an AI Search resource
• Enable role-based access on your search service
• Install Azure Identity client library

Create an AI Search resource

Before continuing with this article, you need an Azure AI Search resource to work with. If you don't have a resource, create your resource now. Enable role-based access control (RBAC) for the resource.

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

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

npm install --save @azure/identity

pip install azure-identity

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.cn"
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=index_name, 
    credential=credential, 
    audience=audience)

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

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 an index
• Search Index Data Reader, query an index

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

Where applicable, replace <identity-id>, <subscription-id>, and <resource-group-name> with your actual values.

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

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.azure.cn/.

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.azure.cn/.
• AZURE_CLIENT_ID: This is the identity to authenticate as.

Related content

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