How to Configure Cosmos DB Service Account

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a cosmos db service account by creating an Azure identity for your app. Next, you assign a data plane role to that identity on your database account. Many teams skip this step and share master keys across apps instead. Shared keys give every app and developer full control over all database data. When a key leaks or permissions are too broad, any script can wipe out production containers. A dedicated identity limits what each app can read or write. How to set up a cosmos db service a

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up a cosmos db service account by creating an Azure identity for your app. Next, you assign a data plane role to that identity on your database account. Many teams skip this step and share master keys across apps instead. Shared keys give every app and developer full control over all database data. When a key leaks or permissions are too broad, any script can wipe out production containers. A dedicated identity limits what each app can read or write.

How to set up a cosmos db service account

In Azure, a service principal or managed identity acts as your cosmos db service account. You start by registering an identity in Microsoft Entra ID for the app. If your app runs on Azure services, you can turn on a system-assigned managed identity. This step removes the need to store client secrets in config files.

Next, you separate control plane permissions from data plane permissions. Control plane roles let users manage the database account itself in the Azure portal. Data plane roles control who can read, write, or delete items inside containers. Your app identity only needs a data plane role to do its job.

Azure provides built-in data plane roles for read-only and read-write tasks. You can also build a custom role that lists exact data actions. Then you scope that role to one database account, one database, or one container. Finally, your app requests a token from Entra ID and connects to the database.

Choosing between managed identities and service principals

Azure offers two main identity types for automated workloads and background jobs. A managed identity works best when your app runs inside the Azure cloud. Azure rotates the underlying credentials on a regular schedule without manual work. Your team does not have to copy secrets into deployment pipelines.

A service principal works better for apps that run outside of Azure. You create an app registration and generate a client secret or upload a certificate. Your team must track when that secret expires and rotate it on time. Both options link to the same data plane role assignments inside the database.

Service-to-Service Authentication + Service Account Governance: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native identity roles solve and what they miss

Moving from master keys to identity roles fixes several big security problems. You can turn off local key logins on the database account right away. When an app leaves service, you delete its identity without breaking other apps. Audit logs in Azure now show which app identity logged in.

Still, native roles only check who logs in at the container level. Once an identity has read or write rights, every query inside that container runs unchecked. A role cannot stop a bad script from deleting thousands of items at once. It also cannot rewrite sensitive fields like emails or phone numbers in query results.

The same problem happens when engineers or automated tools use shared service roles for fixing. The database sees the single role identity, not the person or job behind the query. Teams still need a way to inspect individual queries and mask sensitive fields in flight.

Add runtime guardrails and masking beside your databases and APIs

Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits inline in the protocol beside the service as an open-source proxy, a sidecar for your database or API. On every production query an agent or human runs, hoop.dev decides whether to pass, mask, block, or escalate it for review.

Before a query runs, hoop.dev guardrails check the statement against your rules, an AI Analyzer you configure can score intent or hold risky calls for human approval, and hoop.dev data masking rewrites sensitive fields in responses in memory. Explore the MIT-licensed project on GitHub.

Frequently asked questions

Can I turn off master keys after setting up a service account?

Yes, you can disable local key access on your database account settings. After that change, all apps and users must log in with Entra ID tokens.

What is the smallest scope for a Cosmos DB data plane role?

You can scope a role assignment down to a single container inside a database. The identity will not have rights to read or write in other containers.

How does data masking handle sensitive fields in Cosmos DB queries?

Data masking rewrites matched fields like card numbers, national IDs, or emails in query results. The app or user receives the masked output instead of the raw text.

The query runs. The emails stay hidden.