How to Configure MongoDB Replication User
You set up a mongodb replication user by creating a database account with read roles. This account lets sync tools read data changes without allowing write actions on your database. Teams often start by reusing an admin account for data sync jobs and pipelines. That quick fix gives a background tool the power to drop collections or change data. If an attacker steals that key, they gain full control over every database. A safer plan uses role-based rules to limit what the sync account can do. 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 mongodb replication user by creating a database account with read roles. This account lets sync tools read data changes without allowing write actions on your database.
Teams often start by reusing an admin account for data sync jobs and pipelines. That quick fix gives a background tool the power to drop collections or change data. If an attacker steals that key, they gain full control over every database. A safer plan uses role-based rules to limit what the sync account can do. You define which collections the account can read and block all write commands.
How a mongodb replication user works
MongoDB uses role-based rules to control what a user or app can do. Each role grants a set of actions on a specific database or collection. Self-hosted servers and cloud clusters offer different built-in roles, yet they share the same actions. When you set up an account for data sync, you assign read privileges.
The built-in read role lets an account read all non-system collections in one database. It includes actions to find documents, list collections, check indexes, and open a change stream. That change stream action is vital for sync tools that watch for live updates. The read role blocks actions that insert, update, remove, or drop data.
If a tool must write to a target cluster, it needs the readWrite role there. That role adds the power to insert, update, remove, and drop collections or indexes. For the source database, you should stick to read actions down to the collection level.
How to scope roles for data sync
Start by listing the exact databases and collections your sync job needs to read. Do not assign cluster-wide admin roles when a single database role will work. Create a dedicated account just for the sync tool so you can track its logs. Assign the read role on the source database so the tool can open change streams.
User Provisioning (SCIM) + MongoDB Authentication & Authorization: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
If the job only needs two collections, build a custom role scoped to those collections. This stops the sync tool from reading other tables in the same database. Next, store the account credentials in a secure secret store instead of plain text files. Rotate the password on a regular schedule and remove old accounts when pipelines retire. Check your database logs often to see which host machines log in with this account.
What native roles solve and what they leave open
Native database roles do a great job of stopping unwanted writes at the gate. A read role makes sure a sync script cannot delete a collection by mistake. It also keeps an account confined to the specific databases you choose to share. Still, native roles only check who logs in and which broad actions they run.
Once a user or tool has the read role, it can read every field. The database cannot rewrite sensitive fields like emails or phone numbers in query results. If a collection holds card numbers or national IDs, a read role sends them all. Native roles also struggle when engineers share one sync account to debug a broken pipeline. You see the shared account name in the log, not the person who ran the query. Teams also have to manage long-lived passwords spread across many servers and worker nodes.
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
What role does a MongoDB sync account need on the source database?
It usually needs the read role on the source database or specific collections. This role allows find queries and change streams while blocking all data changes.
Can I limit a replication account to specific collections?
Yes, MongoDB roles can grant access down to the collection level of detail. You can grant read and change stream actions on only the collections you select.
Does a read role hide sensitive fields during data sync?
No, the native read role returns full documents from every allowed collection. To hide emails, phone numbers, or card numbers, you need field masking in flight.
Related guides
In this post