How to Configure Cosmos DB Proxy

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a cosmos db proxy by routing client traffic through an intermediate network host. That host checks user identity and network rules before traffic reaches the database endpoint. Most teams start by sharing primary database keys or setting up broad cloud directory roles. Overly broad roles let any logged-in user read, change, or delete every item across containers. How a native cosmos db proxy setup works Azure gives teams two native ways to control who can log in to the database. Yo

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 proxy by routing client traffic through an intermediate network host. That host checks user identity and network rules before traffic reaches the database endpoint. Most teams start by sharing primary database keys or setting up broad cloud directory roles. Overly broad roles let any logged-in user read, change, or delete every item across containers.

How a native cosmos db proxy setup works

Azure gives teams two native ways to control who can log in to the database. You can use master keys or role-based rules tied to your cloud directory. Most teams combine these identity checks with private network links or firewall rules. When an app or engineer connects, the client SDK chooses between two network modes. Direct mode sends traffic straight to backend storage nodes over a wide range of ports. Gateway mode sends all traffic through a native front-end node over standard web ports.

Teams that need a cosmos db proxy effect often pick this native gateway mode. It keeps firewall rules simple because traffic uses a single predictable port. Admins then add cloud firewall rules to allow traffic only from specific virtual networks. They also assign data plane roles to user groups in the cloud identity portal. When an engineer runs a query, the cloud directory issues a token to the client. The native front-end node checks that token against the assigned role before running the request.

What native network and role rules solve

Native roles and private network rules solve basic perimeter security for your cloud data. Firewall rules stop outside traffic from reaching your database endpoint over the public internet. Directory roles stop teams from pasting master keys into local text files or scripts. Admins can revoke a user role in the directory when someone leaves the team. Cloud logs also show when a user logs in and which network address they used.

Where native database roles fall short

Native roles decide who can log in, not what each query does in flight. Once a user has a read or write role, they have full container access. A single bad query or script can still wipe out thousands of records at once. There is no native way to require a peer check before a delete runs.

Database Proxy (ProxySQL, PgBouncer) + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Native roles also return full documents to anyone with read access on a container. If a document holds emails, phone numbers, card numbers, or national IDs, everything returns in plain text. You cannot set up native roles to rewrite those sensitive fields in query results. You must either build custom views or grant full read access to the raw records. Also, sharing static keys for older tools leaves long-lived secrets on engineer laptops. Rotating those shared keys requires updating every person and service at the exact same time.

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

What is the difference between direct mode and gateway mode in Cosmos DB?

Direct mode connects straight to backend nodes over many ports for lower latency. Gateway mode routes requests through a front-end node over a single standard web port.

Can native Azure roles mask sensitive fields inside a Cosmos DB document?

No, native roles grant access at the container level and return full documents. Masking fields like emails or card numbers requires a layer that rewrites results in flight.

Why do teams avoid sharing Cosmos DB primary master keys with engineers?

Primary keys give full admin control over all data and settings without user attribution. If a key leaks, anyone can read or delete data until you rotate the key.

The query runs. The emails stay hidden.