How to Configure MongoDB Atlas User Roles

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up mongodb atlas user roles by linking action sets to target databases. Each role defines which actions a database user can run down to the collection level. Many teams start by giving broad read and write roles to every engineer. That shortcut speeds up early work, but it puts live production data at risk. One bad command or wide query can change records or expose sensitive customer fields. How mongodb atlas user roles work under the hood MongoDB uses role-based rules to control what

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 mongodb atlas user roles by linking action sets to target databases. Each role defines which actions a database user can run down to the collection level. Many teams start by giving broad read and write roles to every engineer. That shortcut speeds up early work, but it puts live production data at risk. One bad command or wide query can change records or expose sensitive customer fields.

How mongodb atlas user roles work under the hood

MongoDB uses role-based rules to control what database users can do after login. A role combines a set of allowed actions with a specific target resource. When you assign a role on a database, it governs actions inside that database. You can scope permissions across a whole database or down to one specific collection. MongoDB Atlas database users use built-in roles that differ from self-hosted deployment roles. Still, both setups rely on the same core privilege actions to check each request.

For day-to-day queries, teams rely on two primary built-in options: read and readWrite. The read role lets a user view all non-system collections in its assigned database. It also covers the system.js collection and supports actions like find and listCollections. Users with the read role can also run listIndexes, dbStats, collStats, and changeStream. They cannot run insert, update, remove, or dropCollection commands on that database.

The readWrite role includes every action in the read role plus data change rights. Users with readWrite can run insert, update, and remove commands on records. They can also create or drop indexes and create or drop whole collections. When a team needs finer control, admins build custom roles from these exact privilege actions.

What native roles solve and what they leave open

Native roles do a great job of stopping unauthorized logins and broad schema changes. Separating read users from readWrite users stops accidental deletes during routine debugging checks. Scoping a role down to a single collection keeps apps in their own lanes. This setup decides who can log in and which collections they can touch.

Still, collection-level roles cannot see inside the individual queries a user runs in flight. Once a developer has the read role on a customer collection, every field returns. A simple find query pulls back raw emails, phone numbers, card numbers, and national IDs. Native roles do not rewrite matched fields in results based on who runs the query.

User Provisioning (SCIM) + MongoDB Authentication & Authorization: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Write roles carry a similar operational gap during live maintenance or incident fixes. A user with readWrite can fix one broken record or drop an entire collection. The database checks the role at the collection boundary, not the intent of each command. Shared database users make this worse because audit logs only show the shared role name. Teams cannot tell which engineer ran a risky update or pulled sensitive customer fields. Static role assignments also stay active all day, long after a support ticket closes.

How to scope database permissions for engineering teams

Start by separating app service accounts from human users who debug live issues. Give each app a dedicated user scoped only to the collections it needs. Avoid granting readWrite when a service only runs find or changeStream actions. For human engineers, default to read roles on non-sensitive collections whenever possible.

Next, review any role that allows dropCollection, dropIndex, or unrestricted remove actions. Keep those high-impact actions out of standard developer roles used for daily checks. When engineers need to inspect collections with sensitive fields, pair role checks with data masking. Masking rewrites matched fields like emails and card numbers in query results during sessions. Finally, tie every database action back to an individual identity rather than a shared login.

Inspect MongoDB wire traffic in flight

Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev sits inline in the MongoDB protocol next to your server as a sidecar for your MongoDB. On every production command from mongosh, drivers, or AI agents, hoop.dev decides whether to pass, mask, block, or hold it for human review.

First, hoop.dev guardrails block bad deletes, drops, and write pipelines or hold them for approval. Next, hoop.dev data masking rewrites sensitive values in returned documents in memory and logs each decision. Explore the repo on GitHub.

Frequently asked questions

How granular are MongoDB roles?

A role applies to the database where you define it and controls actions on resources. It can grant permissions down to the collection level of granularity for fine control.

What is the difference between the read and readWrite roles?

The read role allows viewing non-system collections through actions like find, listCollections, and changeStream. The readWrite role adds data modification actions including insert, update, remove, createIndex, and dropCollection.

Do MongoDB Atlas database users use the same roles as self-hosted MongoDB?

MongoDB Atlas database users have different built-in role options than self-hosted deployment users. Still, both systems build their roles from the exact same underlying privilege actions.

The query runs. The emails stay hidden.