How to Configure Cosmos DB Read Only User

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a cosmos db read only user by assigning a reader role or key. This restricts accounts to reading items without changing or deleting database records. Many teams start by sharing primary read-only keys across their apps and staff. Broad permissions put live data at risk when a single shared key leaks. Moving to identity roles helps teams track who reads data at any time. How a cosmos db read only user works in Azure Azure gives you two main ways to grant read access to your data. Fi

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 read only user by assigning a reader role or key. This restricts accounts to reading items without changing or deleting database records. Many teams start by sharing primary read-only keys across their apps and staff. Broad permissions put live data at risk when a single shared key leaks. Moving to identity roles helps teams track who reads data at any time.

How a cosmos db read only user works in Azure

Azure gives you two main ways to grant read access to your data. First, you can share a built-in read-only account key with a person. Second, you can link a cloud identity to a data plane reader role. The cloud identity option works much better for human users and local scripts.

To understand why, you must separate control plane and data plane permissions. Control plane roles let people view account settings in the cloud portal. Data plane roles let people read the actual JSON documents inside a container. A true reader setup needs a data plane role with only read actions.

Admins build a role definition that lists allowed actions like reading items. Then they assign that role to a specific user or group identity. They also set the scope to one database or a single container. When the person logs in, the cloud directory checks their identity token. The database then allows query requests and blocks any write or delete calls.

Choosing between shared keys and identity roles

Many teams still pass around the built-in read-only master key for quick debugging. That key grants read rights to every single container in the whole account. You cannot scope a master key down to one safe test collection. Also, shared keys leave no clear name in your audit logs.

When five developers use the same key, every query looks the exact same. If someone runs a heavy query, you cannot tell who sent it. Rotating that key also breaks every script and app using it right away.

Identity roles fix the shared key problem by tying access to one user. When an engineer leaves the team, disabling their main profile stops database access. You can also scope their read role to one specific container. Still, native roles take effort to manage across dozens of databases and teams.

Read-Only Root Filesystem + User Provisioning (SCIM): architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native read roles solve and what they miss

Native reader roles stop people from dropping tables or altering live records. They ensure a support engineer will not overwrite customer items by mistake. This setup solves the basic problem of accidental writes in production databases.

Still, a role check only happens when the user first connects. The database decides who logs in, not what individual queries return in flight. A read role still lets a user pull every record in a container. If that container holds private customer info, the reader sees all of it.

Native roles do not rewrite emails, phone numbers, or card numbers in results. A person with read rights can query thousands of sensitive records at once. Native roles also lack a step to require peer approval per query session. Teams need a way to inspect queries and mask fields like national IDs.

Govern statements and responses across databases and APIs

Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev sits inline in the protocol beside each supported service as an open-source proxy, a sidecar for your database or API. For every query or command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human approval.

First, hoop.dev guardrails block banned queries before they run or hold risky ones for review, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.

Frequently asked questions

Can a portal reader role query items inside a container?

No, a standard portal reader only views account settings on the control plane. To read actual documents, the user needs a data plane reader role assignment.

What is the risk of using the built-in read-only key?

The read-only key grants full read access to every database in the account. It cannot be scoped to one container or tied to one person's name.

Do read-only roles hide sensitive fields inside JSON documents?

No, native read roles return the full document to anyone with read access. You need field masking in your query path to rewrite emails or card numbers.

The query runs. The emails stay hidden.