Implement key rotation in Azure Cosmos DB

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

Rotating keys is a critical part of ensuring that the effect of any potential exposure of your credentials is minimized. You should regenerate the keys at least every 60 days.

Warning

Microsoft recommends that you use the most secure authentication flow available. The authentication flow described in this procedure requires a very high degree of trust in the application, and carries risks that are not present in other flows. You should only use this flow when other more secure flows, such as managed identities, aren't viable.

For Azure Cosmos DB, Microsoft Entra authentication is the most secure authentication mechanism available. Review the appropriate security guide for your API:

• Azure Cosmos DB for NoSQL

Prerequisites

• An existing Azure Cosmos DB account

Rotate your primary or secondary key

You can rotate either of your keys using the Azure portal or through a script.

Azure portal

Use the Azure portal to rotate (or regenerate) either of the four built-in keys:

• Primary read-write
• Primary read-only
• Secondary read-write
• Secondary read-only

1. Sign in to the Azure portal (https://portal.azure.com).

2. Navigate to your existing Azure Cosmos DB account.

3. In the account resource pane, select Keys from the Settings section of the service menu.

4. Select the refresh option for the Primary Key or Secondary Key fields in either the Read-write Keys or Read-only sections.

Azure CLI

Use this Azure CLI script to regenerate one of the keys in your Azure Cosmos DB account.

az cosmosdb keys regenerate \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --key-kind "primary"

--key-kind argument options include:

• primary
• primaryReadonly
• secondary
• secondaryReadonly

For more information, see az cosmosdb keys regenerate

Azure PowerShell

Use this Azure PowerShell script to regenerate one of the keys in your Azure Cosmos DB account.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-account>"
    KeyKind = "primary"
}
New-AzCosmosDBAccountKey @parameters

KeyKind parameter options include:

• primary
• primaryReadonly
• secondary
• secondaryReadonly

For more information, see New-AzCosmosDBAccountKey.

Related content

• Obtain primary/secondary key