Edit

Share via

Configure a search service to connect using a managed identity in Azure AI Search

  • Article

Important

User-assigned managed identity assignment is in public preview under Supplemental Terms of Use. The Management preview REST API provides user-assigned managed identity assignment for Azure AI Search. Support for a system-assigned managed identity is generally available.

You can use Microsoft Entra ID and role assignments for outbound connections from Azure AI Search to resources providing data, applied AI, or vectorization during indexing or queries.

To use roles on an outbound connection, first configure your search service to use either a system-assigned or user-assigned managed identity as the security principal for your search service in a Microsoft Entra tenant. Once you have a managed identity, you can assign roles for authorized access. 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 connect to other Azure resources under its system-assigned or a user-assigned managed identity.

  • Search service configuration of a system-assigned managed identity is generally available.
  • Search service configuration of a user-assigned managed identity is in public preview, under supplemental terms of use.
  • Data plane usage of a managed identity, whether system or user-assigned, is generally available. For example, if you want a user-assigned managed identity on an indexer data source connection, key vault, debug session, or enrichment cache, you can use a generally available REST API version to create the connection, assuming the feature you're using is also generally available.

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, Azure AI Foundry and Azure Functions via skills/vectorizers 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 AI search service currently can't connect to tables on a storage account that has shared key access turned off.

3 Connections to Azure OpenAI, Azure AI Foundry and Azure Functions via skills/vectorizers include: Custom skill, Custom vectorizer, Azure OpenAI embedding skill, Azure OpenAI vectorizer, AML skill and Azure AI Foundry model catalog 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.

  1. Sign in to the Azure portal and find your search service.

  2. Under Settings, select Identity.

  3. On the System assigned tab, under Status, select On.

  4. Select Save.

    Screenshot of the Identity page in Azure portal.

    After you save the settings, the page updates to show an object identifier that's assigned to your search service.

    Screenshot of a system identity object identifier.

Create a user-assigned managed identity

Important

Part of this scenario is in public preview under Supplemental Terms of Use. The Management preview REST API provides user-assigned managed identity configuration for Azure AI Search.

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.

Steps are:

  • In your Azure subscription, create a user-assigned managed identity.
  • On your search service, update the service definition to enable the user-assigned managed identity (this step is in preview).
  • On other Azure services you want to connect to, create a role assignment for the identity.
  • In data source connections on Azure AI Search, such as an indexer data source, reference the user-managed identity in the connection details (this step is generally available if support for the feature is generally available).

A user-assigned managed identity can be scoped to subscriptions, resource groups, or resource types.

Associating a user-assigned managed identity is supported in the Azure portal, in preview versions of the Management REST APIs, and in beta SDK packages that provide the feature.

  1. Sign in to the Azure portal

  2. Select Create a resource.

  3. In the "Search services and marketplace" search bar, search for "User Assigned Managed Identity" and then select Create.

    Screenshot of the user assigned managed identity tile in Azure Marketplace.

  4. Select the subscription, resource group, and region. Give the identity a descriptive name.

  5. Select Create and wait for the resource to finish deploying.

    It takes several minutes before you can use the identity.

  6. In your search service page, under Settings, select Identity.

  7. On the User assigned tab, select Add.

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

  1. Sign in to the Azure portal with your Azure account, and go to your Azure OpenAI resource.

  2. Select Access control from the left menu.

  3. Select Add and then select Add role assignment.

  4. Under Job function roles, select Cognitive Services OpenAI User and then select Next.

  5. Under Members, select Managed identity and then select Members.

  6. Filter by subscription and resource type (Search services), and then select the managed identity of your search service.

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

You can use generally available REST API versions and Azure SDK packages for these connections.

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.

Blob data source (system):

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.

JSON 
"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob data source (user):

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.

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

Knowledge store:

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.

JSON 
"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Enrichment cache:

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

JSON 
"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Debug session:

A debug session runs in the Azure portal and takes a connection string when you start the session. You can paste a string similar to the following example.

JSON 
"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Custom skill:

A custom skill targets the endpoint of an Azure function or app hosting custom code.

  • uri is the endpoint of the function or app.

  • authResourceId tells the search service to connect using a managed identity, passing the application ID of the target function or app in the property.

JSON 
{
  "@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 automatically if "apikey" and "authIdentity" are empty, as demonstrated in the following example. The "authIdentity" property is used for user-assigned managed identity only.

System-managed identity example:

JSON 
{
  "@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"
    }
  ]
}

Here's a vectorizer example configured for a system-assigned managed identity. A vectorizer is specified in a search index.

JSON 
 "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"
      }
    }
  ]

User-assigned managed identity example:

A user-assigned managed identity is used if "apiKey" is empty and a valid "authIdentity" is provided.

JSON 
{
  "@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"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

Here's a vectorizer example configured for a user-assigned managed identity. A vectorizer is specified in a search index.

JSON 
 "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"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

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 and from the Azure portal.

See also