Configure customer-managed key for data encryption at rest for an Azure Cosmos DB for MongoDB vCore cluster

In this article, you learn how to configure customer-managed key (CMK) for data encryption at rest in Azure Cosmos DB for MongoDB vCore. The steps in this guide configure a new Azure Cosmos DB for MongoDB vCore cluster, a replica cluster, or a restored cluster with customer-managed key stored in an Azure Key Vault and user-assigned managed identity.

Prerequisites

• An Azure subscription

  • If you don't have an Azure subscription, create a free account before you begin.

• The latest version of the Azure CLI in Azure Cloud Shell.

  • If you prefer to run CLI reference commands locally, sign in to the Azure CLI by using the az login command.

Prepare user-assigned managed identity and Azure Key Vault

To configure customer-managed key encryption on your Azure Cosmos DB for MonogDB vCore cluster, you need a user-assigned managed identity, an Azure Key Vault instance, and permissions properly configured.

Using the Azure portal:

1. Create one user-assigned managed identity, if you don't have one yet.

2. Create one Azure Key Vault, if you don't have one key store created yet. Make sure that you meet the requirements. Also, follow the recommendations before you configure the key store, and before you create the key and assign the required permissions to the user-assigned managed identity.

3. Create one key in your key store.

4. Grant user-assigned managed identity permissions to the Azure Key Vault instance as outlined in the requirements.

Configure data encryption with customer-managed key during cluster provisioning

Update settings for encryption on cluster with CMK

For existing clusters that were deployed with data encryption using a customer-managed key, you can do several configuration changes. Things that can be changed are the references to the keys used for encryption, and references to the user-assigned managed identities used by the service to access the keys kept in the key stores.

You must update references that your Azure Cosmos DB for MongoDB vCore cluster has to a key:

• When the key stored in the key store is rotated either manually or automatically.
• When you want to use the same or a different key stored in a different key store.

You must update the user-assigned managed identities that are used by your Azure Cosmos DB for MongoDB vCore cluster to access the encryption keys:

• Whenever you want to use a different identity.

You can change user-assigned managed identity and encryption key for data encryption on an existing cluster via a REST API call.

1. Create a JSON file with the following content. Replace placeholders that start with $ sign with the actual values and save the file.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

2. Run the following Azure CLI command to make a REST API call to create an Azure Cosmos DB for MongoDB vCore cluster. Replace placeholders in the variables section and the file name for the --body parameter in the az rest command line with the actual values.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-07-01-preview --body  @jsonFileFromThePreviousStep.json
   

Whether you want to only change the user-assigned managed identity used to access the key, or you want to only change the key used for data encryption, or you want to change both at the same time, you're required to provide all parameters listed in the JSON file.

If the key or the user-assigned managed identity specified don't exist, you get the error.

Identities passed as parameters, if they exist and are valid, are automatically added to the list of user-assigned managed identities associated with your Azure Cosmos DB for MongoDB vCore cluster. This is the case even if the command later fails with some other error.

Change data encryption mode on existing clusters

The only point at which you can decide if you want to use a service-managed key or a customer-managed key (CMK) for data encryption, is at cluster creation time. Once you make that decision and create the cluster, you can't switch between the two options. To create a copy of your Azure Cosmos DB for MongoDB vCore cluster with a different encryption option, you can either create a replica cluster or perform a cluster restore and select the new encryption mode during replica cluster or restored cluster creation.

Related content

• Learn about data encryption at rest in Azure Cosmos DB for MongoDB vCore
• Check out CMK limitations
• Migrate data to Azure Cosmos DB for MongoDB vCore