Rotate keys for Azure Cosmos DB for NoSQL

  • Applies to: ✅ NoSQL, ✅ MongoDB, ✅ Apache Cassandra, ✅ Apache Gremlin, ✅ Table

Warning

Resource Owner Password Credential (ROPC) flow isn't recommended for production Azure Cosmos DB for NoSQL workloads as it requires handling credentials directly, which poses security risks. For more secure authentication, use role-based access control with Microsoft Entra ID. For more information, see role-based access control and Microsoft Entra ID authentication in Azure Cosmos DB for NoSQL.

Azure Cosmos DB for NoSQL allows you to rotate primary and secondary keys to maintain security. This article explains how to regenerate keys while ensuring continuous application access to your database.

Note

Key regeneration can take anywhere from one minute to multiple hours depending on the size of the Azure Cosmos DB for NoSQL account. Ensure your application is consistently using either the primary key or the secondary key before starting the rotation process.

Prerequisites

  • An existing Azure Cosmos DB for NoSQL account

  • Application currently using either primary or secondary key consistently

Rotate keys using account key usage metadata

Important

Account key usage metadata feature is in private preview. This feature is provided without a service-level agreement, and we don't recommend it for production workloads. For more information, see Supplemental Terms of Use for Azure Previews

Azure Cosmos DB now offers additional feature to ensure safe key rotation or disabling local authentication with Account Key Usage Metadata. This feature is designed to provide extra visibility into when an account key was last used, allowing teams to make informed decisions before rotating or migrating to Entra ID.

Screenshot showing account key usage metadata in a Azure Cosmos DB account.

Why is it important?

  • Helps with disabling local authentication: Provides confidence that keys are no longer in use before turning off local auth.
  • Prevents Outages or disruption to your applications: Avoids accidental rotation of actively used keys.
  • Improve Security Hygiene: Encourages safe and intentional key rotation.

This is especially valuable for:

  • Customers currently using keys but planning to migrate fully to Entra ID.
  • Infrequently used keys: Monthly or yearly jobs that still depend on keys.
  • Shared Keys across teams: Where visibility is often limited.

Note

Customers interested in early access using sign up form or reach out to us on cosmosdb-sec-feature@microsoft.com

Rotate keys when using the primary key

If your application is currently using the primary key, follow these steps to rotate to the secondary key and regenerate the primary key.

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

  2. Navigate to your Azure Cosmos DB for NoSQL account.

  3. Select Keys from the navigation menu.

  4. Select Regenerate Secondary Key from the ellipsis menu next to your secondary key.

  5. Validate that the new secondary key works consistently against your Azure Cosmos DB for NoSQL account.

  6. Update your application to use the secondary key instead of the primary key.

  7. Return to the Keys section and select Regenerate Primary Key from the ellipsis menu next to your primary key.

Rotate keys when using the secondary key

If your application is currently using the secondary key, follow these steps to rotate to the primary key and regenerate the secondary key.

  1. In the Keys section of your Azure Cosmos DB for NoSQL account, select Regenerate Primary Key from the ellipsis menu next to your primary key.

  2. Validate that the new primary key works consistently against your Azure Cosmos DB for NoSQL account.

  3. Update your application to use the primary key instead of the secondary key.

  4. Return to the Keys section and select Regenerate Secondary Key from the ellipsis menu next to your secondary key.

Related content

  • Last updated on