Edit

Share via

Connect to Azure Cosmos DB using a managed identity (Azure AI Search)

  • Article

This article explains how to set up an indexer connection to an Azure Cosmos DB database using a managed identity instead of providing credentials in the connection string.'

You can use a system-assigned managed identity or a user-assigned managed identity. Managed identities are Microsoft Entra logins and require Azure role assignments to access data in Azure Cosmos DB. You can optionally enforce role-based access as the only authentication method for data connections by setting disableLocalAuth to true for your Azure Cosmos DB for NoSQL account.

Prerequisites

Supported approaches for managed identity authentication

Azure AI Search supports two mechanisms to connect to Azure Cosmos DB using managed identity.

  • The legacy approach requires configuring the managed identity to have reader permissions on the control plane of the target Azure Cosmos DB account. Azure AI Search utilizes that identity to fetch the account keys of Cosmos DB account in the background to access the data. This approach won't work if the Cosmos DB account has "disableLocalAuth": true.

  • The modern approach requires configuring the managed identity appropriate roles on the control and data plane of the target Azure Cosmos DB account. Azure AI Search will then request an access token to access the data in the Cosmos DB account. This approach works even if the Cosmos DB account has "disableLocalAuth": true.

Indexers that connect to Azure Cosmos DB for NoSQL support both the legacy and the modern approach - the modern approach is highly recommended.

Limitations

  • Indexers that connect to Azure Cosmos DB for Gremlin and MongoDB (currently in preview) only support the legacy approach.

Connect to Azure Cosmos DB for NoSQL

This section outlines the steps to configure connecting to Azure Cosmos DB for NoSQL via the modern approach.

Configure control plane role assignments

  1. Sign in to Azure portal and find your Cosmos DB for NoSQL account.

  2. Select Access control (IAM).

  3. Select Add and then select Role assignment.

  4. From the list of job function roles, select Cosmos DB Account Reader.

  5. Select Next.

  6. Select Managed identity and then select Members.

  7. Filter by system-assigned managed identities or user-assigned managed identities. You should see the managed identity that you previously created for your search service. If you don't have one, see Configure search to use a managed identity. If you already set one up but it's not available, give it a few minutes.

  8. Select the identity and save the role assignment.

For more information, see Use control plane role-based access control with Azure Cosmos DB for NoSQL.

Configure data plane role assignments

The managed identity needs to assigned a role to read from the Cosmos DB account's data plane. The Object (principal) ID for the search service's system/user assigned identity can be found from the search service's "Identity" tab. This step can only be performed via Azure CLI at the moment.

Set variables:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Define a role assignment for the system-assigned identity:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

For more information, see Use data plane role-based access control with Azure Cosmos DB for NoSQL

Configure the data source definition

Once you have configured both control plane and data plane role assignments on the Azure Cosmos DB for NoSQL account, you can set up a connection to it that operates under that role.

Indexers use a data source object for connections to an external data source. This section explains how to specify a system-assigned managed identity or a user-assigned managed identity on a data source connection string. You can find more connection string examples in the managed identity article.

Tip

You can create a data source connection to Cosmos DB in the Azure portal, specifying either a system or user-assigned managed identity, and then view the JSON definition to see how the connection string is formulated.

The REST API, Azure portal, and the .NET SDK support using a system-assigned or user-assigned managed identity.

Connect through system-assigned identity

When you're connecting with a system-assigned managed identity, the only change to the data source definition is the format of the "credentials" property. Provide a database name and a ResourceId that has no account key or password. The ResourceId must include the subscription ID of Azure Cosmos DB, the resource group, and the Azure Cosmos DB account name.

Here's an example using the Create Data Source REST API that exercises the modern approach.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Note

If the IdentityAuthType property isn't part of the connection string, then Azure AI Search defaults to the legacy approach to ensure backward compatibility.

Connect through user-assigned identity

You need to add an "identity" property to the data source definition, where you specify the specific identity (out of several that can be assigned to the search service), that will be used to connect to the Azure Cosmos DB account.

Here's an example using user-assigned identity via the modern approach.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Connect to Azure Cosmos DB for Gremlin/MongoDB (preview)

This section outlines the steps to configure connecting to Azure Cosmos DB for Gremlin/Mongo via the legacy approach.

Configure control plane role assignments

Follow the same steps as before to assign the appropriate roles on the control plane of the Azure Cosmos DB for Gremlin/MongoDB.

Set the connection string

  • For MongoDB collections, add "ApiKind=MongoDb" to the connection string and use a preview REST API.
  • For Gremlin graphs, add "ApiKind=Gremlin" to the connection string and use a preview REST API.
  • For either kinds, only the legacy approach is supported - that is, IdentityAuthType=AccountKey or omitting it entirely is the only valid connection string.

Here's an example to connect to MongoDB collections using system-assigned identity via the REST API

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Here's an example to connect to Gremlin graphs using user-assigned identity.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Run the indexer to verify permissions

Connection information and permissions on the remote service are validated at run time during indexer execution. If the indexer is successful, the connection syntax and role assignments are valid. For more information, see Run or reset indexers, skills, or documents.

Troubleshoot connections

  • For Azure Cosmos DB for NoSQL, check whether the account has its access restricted to select networks. You can rule out any firewall issues by trying the connection without restrictions in place. Refer to Indexer access to content protected by Azure network security for more information

  • For Azure Cosmos DB for NoSQL, if the indexer fails due to authentication issues, ensure that the role assignments have been done both on the control plane and data plane of the Cosmos DB account.

  • For Gremlin or MongoDB, if you recently rotated your Azure Cosmos DB account keys, you need to wait up to 15 minutes for the managed identity connection string to work.

See also