Security & Access Control

Security in Cosmos is a stack — network layer, identity layer, encryption layer. Each is independent; each has a “good default” and a “compliant default.” Most teams need the good default; regulated industries need the compliant one.

The four authentication methods

Master keys (avoid)

Two per account — primary and secondary. They’re full admin — read, write, change throughput, change index policy, delete the account. The connection-string story almost everyone starts with.

When to use — local dev, break-glass admin scripts, brand-new accounts before you’ve set up RBAC. Never in shipped app code.

Resource tokens (legacy, niche)

Server-side, you call users/permissions and generate a short-lived (1 hr default) token scoped to one user, one container or partition. The client uses that token to talk directly to Cosmos.

When to use — a mobile/client-side app that reads only the current user’s data, where you don’t want every read going through your API. Modern apps usually skip this and proxy through their API anyway.

AAD RBAC (modern, default)

Standard Azure RBAC against the Cosmos data plane. Built-in roles:

• Cosmos DB Built-in Data Reader — point reads, queries
• Cosmos DB Built-in Data Contributor — reads + writes + sproc execution
• Cosmos DB Operator — control plane (create containers, change throughput) but no data access

For finer control — define a custom role with specific data actions (Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read, etc.) and assign at the account, database, or container scope.

Combine with Managed Identity — your VM/Function/App Service has an AAD identity, the SDK uses DefaultAzureCredential, no secrets in config.

var client = new CosmosClient(
  accountEndpoint: "https://my-account.documents.azure.com",
  tokenCredential: new DefaultAzureCredential());

This is the recommended pattern for everything new.

Disable local auth

Account-level switch. Once on, master keys stop working — every authentication goes through AAD. Couple this with audit logs (Diagnostic Settings → AuditEvents) and you have a verifiable “no key auth allowed” guarantee.

Network isolation

Three layers, each independently toggle-able.

Default — public, with optional firewall. Cosmos exposes a public DNS endpoint. You can restrict access via IP allow-list (configurable in the portal). Fine for most production; not for regulated workloads.

Service endpoints. Allow specific Azure subnets to reach Cosmos through Microsoft’s backbone, without going over the public internet. Cheap, easy. The Cosmos endpoint still resolves publicly though, so it’s not full isolation.

Private endpoints. Pull Cosmos onto your VNet at a private IP. Combined with “Public network access — disabled,” only resources on the VNet (or peered VNets) can reach the account at all. The DNS resolves to the private IP from inside the VNet. The gold standard for compliance.

Encryption

At rest — always on, AES-256, Microsoft-managed keys. Free, automatic, nothing to configure.

In transit — TLS 1.2 minimum, enforced.

Customer-managed keys (CMK) — you supply the encryption key from Key Vault. Cosmos uses it to encrypt your account’s master key, which encrypts your data keys. Lets you rotate, audit, or revoke at the Key Vault level.

The catch — if Key Vault is unavailable or the key is deleted, Cosmos cannot decrypt your data. There’s no recovery. Lock down Key Vault access carefully (soft-delete + purge protection on the key) and have a documented rotation runbook.

Always Encrypted (client-side) — for sensitive fields (PII, PHI), encrypt on the client before writing, store ciphertext in Cosmos. The Cosmos SDK has a built-in feature that handles key wrapping with Key Vault. Cosmos never sees the plaintext, even if compromised.

A sensible production setup

For a typical app:

• Identity — Managed Identity + AAD RBAC (Data Contributor role on the specific container).
• Network — Private endpoint, public access disabled.
• At rest — Default Microsoft-managed key (CMK only if compliance requires it).
• Local auth — Disabled.
• Audit logs — Diagnostic Settings → Log Analytics, retain for 90 days.
• Master keys — Stored in Key Vault, rotated quarterly, used only by break-glass scripts.

That’s the baseline. Anything stronger is workload-specific.