How to Configure Cosmos DB IAM Authentication

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up cosmos db iam authentication by mapping cloud identities to data roles. Then you turn off shared account keys so apps use tokens to log in. Most teams start with a single master key for every app and developer. That shared key grants full control over every container and item. When one developer leaves or a key leaks, teams must rotate secrets across every service. Moving to identity roles stops this risk, though broad role assignments still leave data exposed. How cosmos db iam aut

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 cosmos db iam authentication by mapping cloud identities to data roles. Then you turn off shared account keys so apps use tokens to log in. Most teams start with a single master key for every app and developer. That shared key grants full control over every container and item. When one developer leaves or a key leaks, teams must rotate secrets across every service. Moving to identity roles stops this risk, though broad role assignments still leave data exposed.

How cosmos db iam authentication works

Cloud databases separate management tasks from daily data reads and writes. Control plane roles let engineers create accounts, change scaling rules, or set up backups. Data plane roles control who can read, write, or delete items inside a container. Standard cloud role menus only cover the control plane by default. To secure the data itself, you must use the built-in data plane role system.

First, you create a managed identity for your app or pick a user group. Next, you pick a built-in data reader or data contributor role. You can also build a custom role that lists exact read or write actions. Then you bind that role to your identity at the database or container scope. When a user or app connects, it asks the cloud directory for a token. The database checks the token signature and role scope before it runs any query. Finally, you disable local key access on the database account so nobody bypasses the directory.

Why role assignments need tighter scope

Teams often grant data contributor roles at the top account level to save time. This shortcut gives every person in that group access to every single container. A developer fixing one minor bug can still query production tables with customer records. If an attacker steals an active user token, they gain that same wide reach.

To reduce this risk, scope role assignments down to a single database or container. Separate read roles from write roles so support engineers do not alter live records. Even with tight scopes, native roles only check who logs in at the door. Once a user has a valid read role, the database returns every field in a document. Native roles cannot hide sensitive fields like emails, phone numbers, or card numbers in results.

Service-to-Service Authentication + AWS IAM Policies: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native cloud roles leave open

Directory roles solve the problem of static master keys sitting in code repos. They make it easy to revoke a user when someone changes jobs. Still, cloud roles stop working once the session starts and the token passes the check. They do not inspect individual queries or filter what comes back from a read request.

An engineer with a read role can still pull full documents containing national IDs. A developer with a write role can still run a bulk delete script by mistake. Native database logs also require extra setup to tie single queries back to one person. Teams that need field-level data masking or query approvals must look beyond basic role bindings.

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 use standard cloud roles to read container items?

No, standard cloud roles only manage the database account and its settings. You must assign a data plane role to read or write items inside containers.

How do I stop developers from using the master key?

You can turn off local key access in the database account settings. Once off, the database rejects all master keys and requires a valid directory token.

Do data plane roles mask sensitive fields in query results?

No, native data roles grant access to the entire document inside a container. If a user can read an item, they receive every field stored in it.

The query runs. The emails stay hidden.