Cuir in eagar

Comhroinn trí

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

  • Alt

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.

Prerequisites

Limitations

Indexer support for Azure Cosmos DB for Gremlin and MongoDB Collections is currently in preview. At this time, a preview limitation requires Azure AI Search to connect using keys. You can still set up a managed identity and role assignment, but Azure AI Search will only use the role assignment to get keys for the connection. This limitation means that you can't configure a role-based approach if your indexers are connecting to Gremlin or MongoDB.

Create a role assignment in Azure Cosmos DB

  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 Configure role-based access control with Microsoft Entra ID for your Azure Cosmos DB account.

Specify a managed identity in a connection string

Once you have a role assignment, you can set up a connection to Azure Cosmos DB for NoSQL 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 CosmosDB 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.

System-assigned managed identity

The REST API, Azure portal, and the .NET SDK support using a system-assigned managed 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.

  • For SQL collections, the connection string doesn't require "ApiKind".
  • For SQL collections, add "IdentityAuthType=AccessToken" if role-based access is enforced as the only authentication method. It isn't applicable for MongoDB and Gremlin collections.
  • 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.

Here's an example of how to create a data source to index data from a Cosmos DB account using the Create Data Source REST API and a managed identity connection string. The managed identity connection string format is the same for the REST API, .NET SDK, and the Azure portal.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
{
    "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=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

User-assigned managed identity

When you're connecting with a user-assigned managed identity, there are two changes to the data source definition:

  • First, the format of the "credentials" property is the 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.

    • For SQL collections, the connection string doesn't require "ApiKind".
    • For SQL collections, add "IdentityAuthType=AccessToken" if role-based access is enforced as the only authentication method. It isn't applicable for MongoDB and Gremlin collections.
    • For MongoDB collections, add "ApiKind=MongoDb" to the connection string
    • For Gremlin graphs, add "ApiKind=Gremlin" to the connection string.

  • Second, you add an "identity" property that contains the collection of user-assigned managed identities. Only one user-assigned managed identity should be provided when creating the data source. Set it to type "userAssignedIdentities".

Here's an example of how to create an indexer data source object using the REST API.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01

{
    "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=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

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.

Troubleshooting

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.

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