Configure customer-managed key (CMK) for data encryption at rest for an Azure DocumentDB cluster

In this article, you learn how to configure customer-managed key (CMK) for data encryption at rest in Azure DocumentDB. The steps in this guide configure a new Azure DocumentDB cluster, a replica cluster, or a restored cluster. CMK setup uses 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

• Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Prepare user-assigned managed identity and Azure Key Vault

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

Important

User-assigned managed identity and Azure Key Vault instance used to configure CMK should be in the same Azure region where Azure DocumentDB cluster is hosted and all belong to the same Microsoft tenant.

Using the Azure portal:

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

2. Create one Azure Key Vault in the cluster region, 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

Portal

1. During provisioning of a new Azure DocumentDB cluster, service-managed or customer-managed keys for cluster data encryption is configured in the Encryption tab. Select the Customer-managed key for Data encryption.

   

2. In User-assigned managed identity section select Change identity.

   

3. In the list of user-assigned managed identities, select the one you want your cluster to use to access the data encryption key stored in an Azure Key Vault.

   

4. Select Add.

   

5. In the Key selection method, choose Select a key .

6. In the Key section, select Change key .

   

7. In the Select a key pane select the Azure Key Vault in the Key vault and encryption key in the Key, and confirm your choices by selecting Select.

   

   Important

   Selected Azure Key Vault instance should be in the same Azure region where Azure DocumentDB cluster is going to be hosted.

8. Confirm selected user-assigned managed identity and encryption key on the Encryption tab and select Review + create to create cluster.

   

REST APIs

You can enable data encryption with user-assigned encryption key, while provisioning a new cluster, via an az rest command.

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": {
           "administrator": {
             "userName": "$adminName",
             "password": "$complexPassword"
           },
           "serverVersion": "8.0",
           "storage": {
             "sizeGb": 32
           },
           "compute": {
             "tier": "M40"
           },
           "sharding": {
             "shardCount": 1
           },
           "highAvailability": {
             "targetMode": "ZoneRedundantPreferred"
           },
         "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Note

   The keyEncryptionKeyUrl should contain the key name but shouldn't contain a specific key version.

2. Run the following Azure CLI command to make a REST API call to create an Azure DocumentDB 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
   $randomIdentifier = (New-Guid).ToString().Substring(0,8)
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="DocumentDB"
   $mongoClustersName="msdocscr$randomIdentifier"
   
   # 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-09-01 --body  @jsonFileFromThePreviousStep.json
   

Update data encryption settings on cluster with CMK enabled

For existing clusters that were deployed with data encryption using a customer-managed key, you can do several configuration changes. You can change the key vault where the encryption key is stored and the encryption key used as a customer-managed key. You can also change the user-assigned managed identity used by the service to access the encryption key kept in the key store.

Portal

1. On the cluster sidebar, under Settings, select Data encryption.

2. In User-assigned managed identity section select Change identity.

   

3. In the list of user-assigned managed identities, select the one you want your cluster to use to access the data encryption key stored in an Azure Key Vault.

   

4. Select Add.

5. In the Key selection method, choose Select a key .

6. In the Key, choose Change key.

   

7. In the Select a key pane select the Azure Key Vault in the Key vault and encryption key in the Key, and confirm your choices by selecting Select.

   

   Important

   Selected Azure Key Vault instance should be in the same Azure region where Azure DocumentDB cluster is hosted.

8. Confirm selected user-assigned managed identity and encryption key on the Data encryption page and select Save to confirm your selections and create replica cluster.

   

REST APIs

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"
             }
           }
         }
   }
   

   Note

   The keyEncryptionKeyUrl should contain the key name but shouldn't contain a specific key version.

2. Run the following Azure CLI command to make a REST API call to create an Azure DocumentDB 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-09-01 --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 DocumentDB 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 DocumentDB 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.

Enable or disable customer-managed key (CMK) data encryption during replica cluster creation

Follow these steps to create a replica cluster with CMK or SMK data encryption to enable or disable CMK on a replica cluster.

Portal

1. On the cluster sidebar, under Settings, select Global distribution.

2. Select Add new read replica.

   

3. Provide a replica cluster name in the Read replica name field.

4. Select a region in the Read replica region. The replica cluster is hosted in the selected Azure region.

   Note

   Replica cluster is always created in the same Azure subscription and resource group as its primary (read-write) cluster.

   

5. In Data encryption section, select the Customer-managed key to enable CMK or Service-managed key to disable CMK on the replica cluster.

   

6. In User-assigned managed identity section select Change identity.

   

7. In the list of user-assigned managed identities, select the one you want your cluster to use to access the data encryption key stored in an Azure Key Vault.

   

8. Select Add.

9. In the Key selection method, choose Select a key .

10. In the Key, choose Change key.

    

11. In the Select a key pane select the Azure Key Vault in the Key vault and encryption key in the Key, and confirm your choices by selecting Select.

    

12. Confirm selected user-assigned managed identity and encryption key on the Global distribution page and select Save to confirm your selections and create replica cluster.

    

REST APIs

To create a replica cluster with CMK enabled in the same region, follow these steps.

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": "$targetRegionName",
             "properties": {
             	"createMode": "GeoReplica",
                   "replicaParameters": {
                     "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$sourceClusterName",
                     "sourceLocation": "sourceRegionName"
                   },
                   "encryption": {
                     "customerManagedKeyEncryption": {
                       "keyEncryptionKeyIdentity": {
                         "identityType": "UserAssignedIdentity",
                         "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                       },
                       "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                     }
                   }
             }
       }
   

   Note

   The keyEncryptionKeyUrl should contain the key name but shouldn't contain a specific key version.

2. Run the following Azure CLI command to make a REST API call to create an Azure DocumentDB 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-09-01 --body  @jsonFileFromThePreviousStep.json
   

Enable or disable customer-managed key (CMK) data encryption during cluster restore

The restore process creates a new cluster with the same configuration in the same Azure region, subscription, and resource group as the original. Follow these steps to create a restored cluster with CMK or SMK enabled.

Portal

1. Select an existing Azure DocumentDB cluster.

2. On the cluster sidebar, under Settings, select Point In Time Restore.

3. Select a date and provide a time (in UTC time zone) in the date and time fields.

   

4. Enter a cluster name in the Restore target cluster name field.

   

5. Enter a cluster admin name for the restored cluster in the Admin user name field.

6. Enter a password for the admin role in the Password and Confirm password fields.

   

7. In Data encryption section, select the Customer-managed key to enable CMK. If you need to have CMK disabled on the restored cluster, select Service-managed key.

   

8. In User-assigned managed identity section select Change identity.

   

9. In the list of user-assigned managed identities, select the one you want your cluster to use to access the data encryption key stored in an Azure Key Vault.

   

10. Select Add.

11. In the Key selection method, choose Select a key .

12. In the Key, choose Change key.

    

13. In the Select a key pane select the Azure Key Vault in the Key vault and encryption key in the Key, and confirm your choices by selecting Select.

    

14. Select Submit to initiate cluster restore.

REST APIs

To restore a cluster with CMK enabled, follow these steps.

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": {
               "administrator": {
                 "userName": "$adminName"
               },
         	"createMode": "PointInTimeRestore",
               "restoreParameters": {
                 "pointInTimeUTC": "yyyy-mm-ddThh:mm:ssZ",
                 "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$restoredClusterName"
               },
               "encryption": {
                 "customerManagedKeyEncryption": {
                   "keyEncryptionKeyIdentity": {
                     "identityType": "UserAssignedIdentity",
                     "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                   },
                   "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                 }
               }
         }
   }
   

   Note

   The keyEncryptionKeyUrl should contain the key name but shouldn't contain a specific key version.

2. Run the following Azure CLI command to make a REST API call to create an Azure DocumentDB 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-09-01 --body  @jsonFileFromThePreviousStep.json
   

Once restored cluster is created, review the list of post-restore tasks.

Related content

• Learn about data encryption at rest in Azure DocumentDB
• Troubleshoot CMK setup
• Check out CMK limitations
• Migrate data to Azure DocumentDB