Connect a search service to other Azure resources using a managed identity

You can configure an Azure Cognitive Search service to connect 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 above.

  • An Azure resource that accepts incoming requests from an Azure Active Directory login that has a valid role assignment.

Supported scenarios

Cognitive 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 an Azure AD-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 managed identity User-assigned managed identity (preview)
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
Custom skills (hosted in Azure Functions or equivalent) 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 One method for specifying an enrichment cache is in the Import data wizard. Currently, the wizard doesn't accept a managed identity connection string for enrichment cache. However, after the wizard completes, you can update the connection string in the indexer JSON definition to specify either a system or user-assigned managed identity, and then rerun the indexer.

Create a system managed identity

When a system-assigned managed identity is enabled, Azure creates an identity for your search service that can be used to authenticate to other Azure services within the same tenant and subscription. You can then use this identity in Azure role-based access control (Azure RBAC) assignments that allow access to data during indexing.

A system-assigned managed identity is unique to your search service and bound to the service for its lifetime.

  1. Sign in to 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 saving, you'll see an object identifier that's been assigned to your search service.

    Screenshot of a system identity object identifier.

Create a user-assigned managed identity (preview)

A user-assigned managed identity is a resource on Azure. It's useful if you need more granularity in role assignments because you can create separate identities for different applications and scenarios.

Important

This feature is in public preview under supplemental terms of use. User-assigned managed identities aren't currently supported for connections to a network-protected storage account. The search request currently requires a public IP address.

  1. Sign in to 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.

    In the next several steps, you'll assign the user-assigned managed identity to your search service.

  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.

Allow firewall access

If your Azure resource is behind a firewall, make sure there's an inbound rule that admits requests from your search service.

Assign a role

A managed identity must be paired with an Azure role that determines permissions on the Azure resource.

  • Data reader permissions are needed for indexer data connections and for accessing a customer-managed key in Azure Key Vault.

  • Contributor (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 are for Azure Storage. If your resource is Cosmos DB or Azure SQL, the steps are similar.

  1. Sign in to Azure portal and find your Azure resource to which the search service must have access.

  2. In Azure Storage, select Access control (AIM) on the left navigation pane.

  3. Select Add role assignment.

  4. On the Role page, choose a role:

    Role Usage
    Reader and Data Access Grants read permissions for indexer access to content in Azure Table Storage and Azure File Storage.
    Storage Blob Data Reader Grants read permissions for indexer access to content in Blob Storage and Azure Data Lake Storage Gen2.
    Storage Blob Data Contributor Grants write permissions necessary for debug sessions, knowledge store object projections, and enrichment cache.
    Storage Table Data Contributor Grants write permissions necessary for knowledge store table projections.
  5. On the Members page, select Managed Identity.

  6. Select members. In the Select managed identity page, choose your subscription and then filter by service type, and then select the service. Only those services that have a managed identity will be available to select.

    Screenshot of the select managed identity pane in the role assignment wizard.

  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.

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. Azure AD will authenticate 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};"
    }

Blob data source (user):

A search request to Azure Storage can also be made under a user-assigned managed identity, currently in preview. The search service user identity is specified in the "identity" property. You can use either the portal or the REST API preview version 2021-04-30-Preview to set the identity.

"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. On Azure Storage, a knowledge store will create projections as blobs and tables. The connection string is the unique resource ID of your storage account. Notice that the string does not 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};",

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

"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 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};",

Custom skill:

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

See also