Configure a search service to connect using a managed identity
You can configure an Azure AI Search service to make outbound connections to other Azure resources using a system-assigned or user-assigned managed identity and an Azure role assignment. Managed identities and role assignments eliminate the need for passing secrets and credentials in a connection string or code.
Prerequisites
A search service at the Basic tier or higher, any region.
An Azure resource that accepts incoming requests from a Microsoft Entra security principal that has a valid role assignment.
Supported scenarios
Azure AI Search can use a system-assigned or user-assigned managed identity on outbound connections to Azure resources. A system managed identity is indicated when a connection string is the unique resource ID of a Microsoft Entra ID-aware service or application. A user-assigned managed identity is specified through an "identity" property.
A search service uses Azure Storage as an indexer data source and as a data sink for debug sessions, enrichment caching, and knowledge store. For search features that write back to storage, the managed identity needs a contributor role assignment as described in the "Assign a role" section.
| Scenario | System | User-assigned |
|---|---|---|
| Indexer connections to supported Azure data sources 1 | Yes | Yes |
| Azure Key Vault for customer-managed keys | Yes | Yes |
| Debug sessions (hosted in Azure Storage) 1 | Yes | No |
| Enrichment cache (hosted in Azure Storage) 1, 2 | Yes | Yes |
| Knowledge Store (hosted in Azure Storage) 1 | Yes | Yes |
| Connections to Azure OpenAI or Azure AI 3 | Yes | Yes |
1 For connectivity between search and storage, your network security configuration imposes constraints on which type of managed identity you can use. Only a system managed identity can be used for a same-region connection to storage via the trusted service exception or resource instance rule. See Access to a network-protected storage account for details.
2 For enrichment caching in Azure table storage, the search service currently can't connect to tables on a storage account that has shared key access turned off.
3 Connections to Azure OpenAI or Azure AI include: Custom skill, Custom vectorizer, Azure OpenAI embedding skill, Azure OpenAI vectorizer, AML skill, Azure AI Studio model catalog vectorizer, Azure AI Vision multimodal embeddings skill, Azure AI Vision vectorizer.
Create a system managed identity
When you enable a system-assigned managed identity, Microsoft Entra ID creates an identity for your search service that can be used to authenticate to other Azure services within the same tenant. You can then use this identity in role assignments for accessing data and models.
A system-assigned managed identity is unique to your search service and bound to the service for its lifetime. A search service can only have one system-assigned managed identity.
Sign in to the Azure portal and find your search service.
Under Settings, select Identity.
On the System assigned tab, under Status, select On.
Select Save.
After you save the settings, the page updates to show an object identifier that's assigned to your search service.
Create a user-assigned managed identity
A user-assigned managed identity is a resource on Azure. You can create multiple user-assigned managed identities if you want more granularity in role assignments. For example, you might want separate identities for different applications and scenarios.
A user-assigned managed identity can be scoped to subscriptions, resource groups, or resource types.
Sign in to the Azure portal
Select Create a resource.
In the "Search services and marketplace" search bar, search for "User Assigned Managed Identity" and then select Create.
Select the subscription, resource group, and region. Give the identity a descriptive name.
Select Create and wait for the resource to finish deploying.
It takes several minutes before you can use the identity.
In your search service page, under Settings, select Identity.
On the User assigned tab, select Add.
Choose the subscription and then select the user-assigned managed resource that you created in the previous step.
Assign a role
Once you have a managed identity, assign roles that determine search service permissions on the Azure resource.
Read permissions are needed for indexer data connections and for accessing a customer-managed key in Azure Key Vault.
Write permissions are needed for AI enrichment features that use Azure Storage for hosting debug session data, enrichment caching, and long-term content storage in a knowledge store.
The following steps illustrate the role assignment workflow. This example is for Azure OpenAI. For other Azure resources, see Connect to Azure Storage, Connect to Azure Cosmos DB, or Connect to Azure SQL.
Sign in to the Azure portal with your Azure account, and go to your Azure OpenAI resource.
Select Access control from the left menu.
Select Add and then select Add role assignment.
Under Job function roles, select Cognitive Services OpenAI User and then select Next.
Under Members, select Managed identity and then select Members.
Filter by subscription and resource type (Search services), and then select the managed identity of your search service.
Select Review + assign.
Connection string examples
Once a managed identity is defined for the search service and given a role assignment, outbound connections can be modified to use the unique resource ID of the other Azure resource. Here are some examples of connection strings for various scenarios.
Tip
You can create most of these objects in the Azure portal, specifying either a system or user-assigned managed identity, and then view the JSON definition to get the connection string.
An indexer data source includes a "credentials" property that determines how the connection is made to the data source. The following example shows a connection string specifying the unique resource ID of a storage account.
Microsoft Entra ID authenticates the request using the system managed identity of the search service. Notice that the connection string doesn't include a container. In a data source definition, a container name is specified in the "container" property (not shown), not the connection string.
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
A search request to Azure Storage can also be made under a user-assigned managed identity. The search service user identity is specified in the "identity" property.
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
},
. . .
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
}
A knowledge store definition includes a connection string to Azure Storage. The connection string is the unique resource ID of your storage account. Notice that the string doesn't include containers or tables in the path. These are defined in the embedded projection definition, not the connection string.
"knowledgeStore": {
"storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}
An indexer creates, uses, and remembers the container used for the cached enrichments. It's not necessary to include the container in the cache connection string. You can find the object ID on the Identity page of your search service in the portal.
"cache": {
"enableReprocessing": true,
"storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
A debug session runs in the portal and takes a connection string when you start the session. You can paste a string similar to the following example.
"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",
A custom skill targets the endpoint of an Azure function or app hosting custom code. The endpoint is specified in the custom skill definition. The presence of the "authResourceId" tells the search service to connect using a managed identity, passing the application ID of the target function or app in the property.
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "A custom skill that can identify positions of different phrases in the source text",
"uri": "https://contoso.count-things.com",
"authResourceId": "<Azure-AD-registered-application-ID>",
"batchSize": 4,
"context": "/document",
"inputs": [ ... ],
"outputs": [ ...]
}
Azure OpenAI embedding skill and Azure OpenAI vectorizer:
An Azure OpenAI embedding skill and vectorizer in AI Search target the endpoint of an Azure OpenAI service hosting an embedding model. The endpoint is specified in the Azure OpenAI embedding skill definition and/or in the Azure OpenAI vectorizer definition. The system-managed identity is used if configured and if the "apikey" and "authIdentity" are empty. The "authIdentity" property is used for user-assigned managed identity only.
{
"@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
"description": "Connects a deployed embedding model.",
"resourceUri": "https://url.openai.azure.com/",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "embedding"
}
]
}
"vectorizers": [
{
"name": "my_azure_open_ai_vectorizer",
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://url.openai.azure.com",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002"
}
}
]
Check for firewall access
If your Azure resource is behind a firewall, make sure there's an inbound rule that admits requests from your search service.
For same-region connections to Azure Blob Storage or Azure Data Lake Storage Gen2, use a system managed identity and the trusted service exception. Optionally, you can configure a resource instance rule to admit requests.
For all other resources and connections, configure an IP firewall rule that admits requests from Search. See Indexer access to content protected by Azure network security features for details.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for