Configure managed identities with Microsoft Entra ID for your Azure Cosmos DB account

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

Managed identities for Azure resources provide Azure services with an automatically managed identity in Microsoft Entra ID. This article shows how to create a managed identity for Azure Cosmos DB accounts.

Prerequisites

• If you're unfamiliar with managed identities for Azure resources, see What are managed identities for Azure resources?. To learn about managed identity types, see Managed identity types.
• To set up managed identities, your account needs to have the DocumentDB Account Contributor role.

Add a system-assigned identity

Using the Azure portal

To enable a system-assigned managed identity on an existing Azure Cosmos DB account, navigate to your account in the Azure portal and select Identity from the left menu.

Under the System assigned section, flip the Status to On and select Save. You will be asked to confirm the creation of the system-assigned managed identity.

Once the identity has been created and assigned, you can retrieve its Object (principal) ID.

Using an Azure Resource Manager (ARM) template

Important

Make sure to use an apiVersion of 2021-03-15 or higher when working with managed identities.

To enable a system-assigned identity on a new or existing Azure Cosmos DB account, include the following property in the resource definition:

"identity": {
    "type": "SystemAssigned"
}

The resources section of your ARM template should then look like the following:

"resources": [
    {
        "type": " Microsoft.DocumentDB/databaseAccounts",
        "identity": {
            "type": "SystemAssigned"
        },
        // ...
    },
    // ...
]

Once your Azure Cosmos DB account has been created or updated, it will show the following property:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<azure-ad-tenant-id>",
    "principalId": "<azure-ad-principal-id>"
}

Using the Azure CLI

To enable a system-assigned identity while creating a new Azure Cosmos DB account, add the --assign-identity option:

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --assign-identity

You can also add a system-assigned identity on an existing account using the az cosmosdb identity assign command:

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

az cosmosdb identity assign \
    -n $accountName \
    -g $resourceGroupName

Once your Azure Cosmos DB account has been created or updated, you can fetch the identity assigned with the az cosmosdb identity show command:

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

az cosmosdb identity show \
    -n $accountName \
    -g $resourceGroupName

{
    "type": "SystemAssigned",
    "tenantId": "<azure-ad-tenant-id>",
    "principalId": "<azure-ad-principal-id>"
}

Add a user-assigned identity

Using the Azure portal

To enable a user-assigned managed identity on an existing Azure Cosmos DB account, navigate to your account in the Azure portal and select Identity from the left menu.

Under the user assigned section, select + Add.

Find and select all the identities you wish to assign to your Azure Cosmos DB account, then select Add.

Using an Azure Resource Manager (ARM) template

Important

Make sure to use an apiVersion of 2021-03-15 or higher when working with managed identities.

To enable a user-assigned identity on a new or existing Azure Cosmos DB account, include the following property in the resource definition:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<identity-resource-id>": {}
    }
}

The resources section of your ARM template should then look like the following:

"resources": [
    {
        "type": " Microsoft.DocumentDB/databaseAccounts",
        "identity": {
            "type": "UserAssigned",
            "userAssignedIdentities": {
                "<identity-resource-id>": {}
            }
        },
        // ...
    },
    // ...
]

After your Azure Cosmos DB account has been created or updated, it will show the following property:

"identity": {
    "type": "UserAssigned",
    "tenantId": "<azure-ad-tenant-id>",
    "principalId": "<azure-ad-principal-id>"
}

Using the Azure CLI

To enable a user-assigned identity while creating a new Azure Cosmos DB account, add the --assign-identity option and pass the resource ID of the identity you wish to assign:

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --assign-identity <identity-resource-id>

You can also add a user-assigned identity on an existing account using the az cosmosdb identity assign command:

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

az cosmosdb identity assign \
    -n $accountName \
    -g $resourceGroupName
    --identities <identity-resource-id>

After your Azure Cosmos DB account has been created or updated, you can fetch the identity assigned with the az cosmosdb identity show command:

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

az cosmosdb identity show \
    -n $accountName \
    -g $resourceGroupName

{
    "type": "UserAssigned",
    "tenantId": "<azure-ad-tenant-id>",
    "principalId": "<azure-ad-principal-id>"
}

Remove a system-assigned or user-assigned identity

Using an Azure Resource Manager (ARM) template

Important

Make sure to use an apiVersion of 2021-03-15 or higher when working with managed identities.

To remove a system-assigned identity from your Azure Cosmos DB account, set the type of the identity property to None:

"identity": {
    "type": "None"
}

Using the Azure CLI

To remove all managed identities from your Azure Cosmos DB account, use the az cosmosdb identity remove command:

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

az cosmosdb identity remove \
    -n $accountName \
    -g $resourceGroupName

Next steps

Tutorial: Store and use Azure Cosmos DB credentials with Azure Key Vault

• Learn more about managed identities for Azure resources
• Learn more about customer-managed keys on Azure Cosmos DB