Azure Cosmos DB Safe Key Rotation That Prevents Credential Risk

In this blog post Azure Cosmos DB Safe Key Rotation That Prevents Credential Risk we will explain why database keys become difficult to control, how Microsoft’s safer rotation checks help, and how to replace credentials without interrupting customers or internal operations.

At a high level, Azure Cosmos DB is Microsoft’s cloud database for applications that need fast access to large or rapidly changing datasets. An application must prove it is allowed to access the database, often by presenting a primary or secondary account key.

Those keys work much like powerful shared passwords. The problem is rarely the strength of the key itself. The problem is that copies can end up in applications, deployment tools, scripts, support utilities and configuration files, with nobody completely certain which systems still depend on them.

Why an old Cosmos DB key creates a business risk

Many organisations create a Cosmos DB account, connect the first application using the primary key and then leave that credential unchanged for years. It works, so it receives little attention.

Over time, however, the key may be copied into test environments, developer laptops, automation scripts or third-party integration platforms. A former employee, compromised application or exposed configuration file could provide an attacker with a credential that remains valid indefinitely.

Read-write account keys can provide broad access to the database account. That makes a leaked key more serious than an ordinary user password with limited permissions.

Regular rotation reduces the useful lifetime of a stolen credential. It also provides evidence that your organisation actively manages privileged access rather than simply trusting credentials created several years ago.

What safe key rotation actually does

Azure Cosmos DB provides two main account keys, known as the primary and secondary keys. Both can be valid at the same time, allowing an organisation to replace one while applications continue using the other.

The basic idea is straightforward:

1. Identify which key applications currently use.
2. Regenerate the other, inactive key.
3. Update applications to use the newly generated key.
4. Confirm that every application, script and scheduled job still works.
5. Regenerate the old key so any forgotten copies stop working.

The dangerous part is step three. If even one forgotten workload still uses the old key, rotating it can stop orders, customer logins, reporting jobs or operational integrations.

Microsoft’s safe rotation capability adds account key usage information and a check before key regeneration. When enabled, Azure can block the change if the check indicates that the selected key is still being used. The same protection can help when disabling key-based authentication completely.

This is an important safety net, but it should not replace a proper dependency inventory. Monthly reporting jobs, annual processes and rarely used support tools can be easy to miss. Safe rotation combines Azure’s visibility with your team’s knowledge of the business.

A common scenario in a growing business

Consider a 200-person company with a customer portal, mobile application and finance reporting process connected to Cosmos DB. The technology team knows the portal uses the primary key, but nobody remembers that a finance script created two years earlier uses the secondary key.

If the secondary key is regenerated without checking, the customer portal remains healthy. The problem may not appear until month-end, when finance cannot produce a critical report.

A safer process identifies the script, assigns it an owner and includes it in testing. The rotation can then proceed without an outage, while the business gains confidence that old credential copies are no longer useful.

A practical safe rotation process

1. Build a dependency register

List every application, integration, script and external supplier that connects to the Cosmos DB account. Record the business owner, technical owner, environment and authentication method.

Search application settings, deployment pipelines and secret stores for the account endpoint and connection-string references. Do not copy live keys into spreadsheets or support tickets while doing this.

2. Enable the safe rotation checks

The following Azure CLI command enables the relevant account capabilities. Azure CLI is Microsoft’s command-line administration tool. Test this first in a non-production account because one capability is identified as a preview feature and availability can change.

az cosmosdb update \
 --resource-group <resource-group> \
 --name <cosmos-account> \
 --capabilities \
 EnableAccountKeysLastUsageCheckInDisableLocalAuth \
 EnableKeyCheckBeforeRegenerationPreview

You can confirm the enabled capabilities without displaying the actual account keys:

az cosmosdb show \
 --resource-group <resource-group> \
 --name <cosmos-account> \
 --query "capabilities[].name" \
 --output table

3. Regenerate only the inactive key

If production applications currently use the primary key, regenerate the secondary key first. Never regenerate both keys together.

az cosmosdb keys regenerate \
 --resource-group <resource-group> \
 --name <cosmos-account> \
 --key-kind secondary

Key regeneration may take from a minute to several hours for some accounts. Do not assume that clicking the button means every part of the process has completed immediately.

4. Update applications through a controlled secret store

Place the new credential in Azure Key Vault, which securely stores passwords, keys and other sensitive information. Applications should retrieve the secret through controlled access rather than storing it directly in code.

Update one workload at a time where possible. Confirm database connections, customer transactions, background processing and error rates before moving to the next system.

For a more detailed operational sequence, see our Cosmos DB key rotation runbook for avoiding application outages.

5. Wait long enough to find forgotten workloads

A five-minute health check is not enough. Your observation period should cover scheduled jobs, overnight processing, reporting cycles and integrations that run only on certain days.

Monitor failed requests and application logs. Confirm success with business teams, not only with a technical dashboard. A database connection can appear healthy while an important finance or customer process is still broken.

6. Regenerate the previously active key

Once every known workload uses the new key, regenerate the old one. This is the step that closes the security gap because forgotten copies of the previous credential will no longer work.

Record who approved the rotation, when it occurred, what was tested and whether any exceptions remain. That evidence is useful during customer reviews, cyber insurance assessments and compliance audits.

The better long-term answer is fewer shared keys

Rotating shared keys is safer than leaving them unchanged, but the strongest credential is one your application does not need to store.

For supported Cosmos DB workloads, Microsoft Entra ID and managed identities allow an Azure application to use its own verified identity. Azure manages the authentication process, while role-based access control limits what the application can do.

In plain English, each application receives its own access rather than sharing one powerful database password. If an application is retired or compromised, its access can be removed without changing credentials for every other system.

This approach also makes accountability clearer. You can see which identity accessed the service and grant only the permissions it needs.

Our guide to using managed identity in production and Azure CLI locally explains a practical way to remove stored production secrets without slowing developers down.

Do not confuse access keys with encryption keys

Cosmos DB account keys control who can connect to the database. Customer-managed encryption keys control how stored data is encrypted. They address different risks and require different operating processes.

If your organisation is considering greater control over encryption keys for sovereignty or contractual reasons, read what to assess before adopting external key management in Azure.

What technology leaders should require

• A named owner for every Cosmos DB account and connected workload.
• A documented rotation schedule based on business risk.
• Safe rotation checks enabled and tested before production use.
• Keys stored in Key Vault rather than code, documents or tickets.
• Monitoring that covers scheduled and low-frequency workloads.
• A plan to move suitable applications to managed identity.
• Azure Policy reporting for accounts with overdue key regeneration.

These controls support stronger security governance and the intent of the Essential Eight, the Australian Government’s cybersecurity framework that many organisations use as a baseline. Key rotation alone does not make a business Essential Eight compliant, but unmanaged privileged credentials can undermine otherwise strong controls.

Reduce risk without creating another outage

Safe Cosmos DB key rotation is not simply an Azure administration task. Done well, it reduces the value of leaked credentials, improves audit readiness and protects the availability of customer-facing services.

The best result is a repeatable process today and a gradual move away from shared keys tomorrow.

CloudProInc is a Melbourne-based Microsoft Partner and Wiz Security Integrator with more than 20 years of hands-on enterprise IT experience. If you are unsure where your Cosmos DB keys are being used, or whether rotating them could interrupt the business, we are happy to review the setup and help you plan a safe path forward — no strings attached.