Encrypt Cosmos DB with Customer-Managed Keys in Azure Key Vault (2026)

Azure Key Vault’s customer-managed keys (CMK) feature allows you to encrypt your Cosmos DB data at rest using keys that you control, rather than Azure’s automatically managed keys.

Let’s see this in action. Imagine we have a Cosmos DB account mycosmosdbaccount and we want to encrypt it with a key mycosmosdbkey stored in Azure Key Vault mykeyvault.

First, we need to ensure our Key Vault is configured for CMK. This involves granting the Cosmos DB resource provider permission to access the key.

# Get the Cosmos DB resource provider's service principal ID
RP_SP_ID=$(az ad sp list --display-name "Microsoft.DocumentDB" --query "[].objectId" -o tsv)

# Grant the RP permission to get and wrap/unwrap keys on our Key Vault
az keyvault set-policy \
    --name mykeyvault \
    --resource-group myresourcegroup \
    --object-id $RP_SP_ID \
    --key-permissions get wrapKey unwrapKey

Next, we need to create a key in Key Vault.

az keyvault key create \
    --vault-name mykeyvault \
    --name mycosmosdbkey \
    --kty RSA \
    --size 2048

Now, we can associate this key with our Cosmos DB account. This is done by updating the Cosmos DB account properties.

# Get the Key Vault URI and the Key URI
KEY_VAULT_URI=$(az keyvault show --name mykeyvault --query properties.vaultUri -o tsv)
KEY_URI="${KEY_VAULT_URI}keys/mycosmosdbkey"

# Update the Cosmos DB account to use the customer-managed key
az cosmosdb update \
    --name mycosmosdbaccount \
    --resource-group myresourcegroup \
    --key-uri $KEY_URI

This operation might take a few minutes to propagate. Once complete, all data written to this Cosmos DB account will be encrypted using the specified key in Key Vault. If you disable or delete the key, your Cosmos DB data will become inaccessible.

The mental model here is that Cosmos DB is not performing the encryption itself. Instead, it’s delegating the encryption and decryption operations to Azure Key Vault. When data needs to be written, Cosmos DB sends the plaintext data to Key Vault to be encrypted, and when data is read, it sends the ciphertext to Key Vault for decryption. This means Key Vault becomes a critical dependency for your Cosmos DB data availability.

A common point of confusion is how Key Vault access policies and Azure RBAC interact. While Key Vault access policies are essential for granting the Cosmos DB resource provider the specific get, wrapKey, and unwrapKey permissions, Azure RBAC roles (like Cosmos DB Contributor or Owner) are necessary for the user or service principal performing the az cosmosdb update command to have the authority to modify the Cosmos DB account’s encryption settings. Without the correct RBAC permissions on the Cosmos DB account, the az cosmosdb update command will fail, even if Key Vault policies are perfectly configured.

The next step you’ll likely encounter is managing key rotation and understanding the implications of disabling or deleting your CMK.