How to Rotate Cosmos DB Keys and Move to Entra ID Authentication

Retrospective: this article looks back at events from August 2021, written in 2026 with the benefit of hindsight.

Cosmos DB primary keys grant full access to a database. ChaosDB showed how damaging a leaked key can be. Here is how to rotate keys and move to Entra ID role-based access.

Step 1: Inventory key usage

List applications and services connecting to each Cosmos DB account and how they authenticate (key in a connection string, key from Key Vault, or Entra ID).

Step 2: Rotate keys safely

Cosmos DB has a primary and secondary key for zero-downtime rotation:

1. Update applications to use the secondary key.
2. Regenerate the primary key.
3. Move applications back to the new primary key.
4. Regenerate the secondary key.

Store keys in Azure Key Vault, not in application configuration files.

Step 3: Move to Entra ID authentication

Cosmos DB supports role-based access control with Entra ID for data plane operations (for the NoSQL API, with growing support for others):

1. Assign built-in or custom Cosmos DB data plane roles (for example, Cosmos DB Built-in Data Contributor) to the application's managed identity.
2. Update the SDK client to use DefaultAzureCredential or a managed identity credential instead of the key.
3. Test thoroughly.

Step 4: Disable key-based authentication

Once all clients use Entra ID, set disableLocalAuth to true on the account so keys can't be used at all. Use Azure Policy to audit or enforce this across subscriptions.

Step 5: Restrict network access

Use private endpoints and disable public network access.

Step 6: Monitor

Enable diagnostic logs (data plane requests) and Defender for Azure Cosmos DB for anomaly detection.