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

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.

The Identity menu entry

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.

Enabling a system-assigned identity

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

Retrieving the object ID of a system-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 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='China North 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.

The Identity menu entry

Under the user assigned section, select + Add.

Enabling a user-assigned identity

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

Selecting all the identities to assign

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='China North 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