MongoDB Atlas security becomes simple once you stop treating “Atlas access” and “database access” as one thing.
They are two different systems:
Atlas access = Who can manage Atlas?
Database access = Who can connect to MongoDB and read/write data?
MongoDB’s own docs make this separation clear: Atlas users access the Atlas application, while database users access MongoDB databases. Atlas Admin API access also does not allow reading or writing cluster data; for that, a client must authenticate to the cluster as a database user with the right roles. (MongoDB)
1. Big Picture: The Two Security Planes
MongoDB Atlas has two major security planes.
Control Plane: Atlas Management Access
This is for managing Atlas itself.
Examples:
Create organization
Create project
Create cluster
Create database users
Manage backups
Manage IP access list
Manage private endpoints
Manage alerts
Use Atlas UI
Use Atlas Administration API
The identities here are:
Atlas users
Teams
Service accounts
Legacy API keys
The permissions here are:
Organization roles
Project roles
Data Plane: MongoDB Database Access
This is for connecting to the actual database.
Examples:
Connect with mongosh
Connect from application code
Use MongoDB Compass
Run find / insert / update / delete
Read collections
Write documents
Create indexes
Run aggregation
The identities here are:
Database users
Application identities
Workload identities
The permissions here are:
MongoDB database roles
Built-in roles
Custom database roles
Specific privileges
2. The Most Important Diagram
flowchart TD
A[Human or Machine] --> B{What are they trying to access?}
B -->|Manage Atlas| C[Atlas Control Plane]
B -->|Read or write documents| D[MongoDB Data Plane]
C --> C1[Atlas User]
C --> C2[Team]
C --> C3[Service Account]
C --> C4[Legacy API Key]
C1 --> C5[Organization Role]
C2 --> C5
C3 --> C5
C4 --> C5
C5 --> C6[Project Role]
C6 --> C7[Can manage projects, clusters, users, backup, network, alerts]
D --> D1[Network Access Check]
D1 --> D2[Database Authentication]
D2 --> D3[Database Authorization]
D3 --> D4[Can read/write database resources]
D2 --> D5[Database User]
D3 --> D6[MongoDB Role: read, readWrite, custom role, etc.]
Translation:
Atlas role decides what you can do in Atlas.
Database role decides what you can do inside MongoDB.
Network access decides whether you can reach the cluster at all.
Tiny but deadly important.
3. Authentication vs Authorization
Authentication
Authentication answers:
Who are you?
Examples:
Atlas UI login with username/password, SSO, MFA
Service account OAuth token for Atlas Admin API
Database username/password using SCRAM
AWS IAM database authentication
X.509 database authentication
OIDC database authentication
LDAP database authentication
Atlas supports several authentication mechanisms across UI, API, and database access, including service accounts for API access and database authentication options such as SCRAM, X.509, AWS IAM, LDAP, and OIDC/OAuth-based approaches depending on the access type and setup. (MongoDB)
Authorization
Authorization answers:
What are you allowed to do?
Examples:
Can this user create a project?
Can this user pause a cluster?
Can this user create database users?
Can this app read orders?
Can this app write payments?
Can this analyst read only reporting data?
Atlas uses RBAC for management authorization, and MongoDB uses role-based authorization for database-level privileges. MongoDB roles grant actions on resources, and those resources can be scoped as tightly as database or collection level. (MongoDB)
4. Atlas Resource Hierarchy
Atlas resources are usually organized like this:
flowchart TD
ORG[Organization] --> TEAM[Teams]
ORG --> USER[Atlas Users]
ORG --> SA[Service Accounts / API Keys]
ORG --> PROJECT[Project]
PROJECT --> CLUSTER[Cluster]
PROJECT --> NET[Network Access]
PROJECT --> DBACCESS[Database Access]
PROJECT --> BACKUP[Backups]
PROJECT --> ALERTS[Alerts]
PROJECT --> LOGS[Logs]
PROJECT --> CUSTOMROLES[Custom Database Roles]
CLUSTER --> DB1[Database: app_db]
CLUSTER --> DB2[Database: reporting_db]
DB1 --> C1[Collection: users]
DB1 --> C2[Collection: orders]
DB2 --> C3[Collection: daily_sales]
Organization
The organization is the top-level administrative boundary.
It contains:
Projects
Atlas users
Teams
Billing settings
Organization-level service accounts / API keys
Organization roles
Typical organization-level roles include:
| Role | Meaning |
|---|---|
| Organization Owner | Root-level organization access |
| Organization Project Creator | Can create projects |
| Organization Billing Admin | Can manage billing |
| Organization Billing Viewer | Can view billing |
| Organization Read Only | Can view organization settings, users, and projects |
| Organization Member | Can view organization settings/users and only projects they belong to |
An Organization Owner gets broad root-level organization access, including Project Owner access to all projects, organization administration, user/database-user management, and the combined privileges of other organization roles. (MongoDB)
Project
A project is one of the most important security boundaries in Atlas.
A project contains:
Clusters
Database users
Custom database roles
IP access list
Private endpoint configuration
Backups
Alerts
Project-level Atlas users / teams / service accounts
Most teams use projects to separate environments:
dev project
qa project
staging project
prod project
That gives you clean boundaries:
Developers can have broad access in dev.
Developers can have limited access in staging.
Developers can have read-only or no data access in prod.
Production apps get production-only database users.
CI/CD gets specific project-level service account roles.
5. Atlas Users
An Atlas user is a human account that logs in to Atlas.
Example:
rajesh@example.com logs in to cloud.mongodb.com
An Atlas user can be granted:
Organization roles
Project roles
That user may be able to:
View projects
Create clusters
Manage database users
View metrics
Use Data Explorer
Manage IP access list
Manage backups
Invite users
But remember:
Atlas user ≠ MongoDB database user
An Atlas user may manage a database user, but that does not automatically mean the same human can connect to the database using that Atlas login.
6. Teams
A team is a group of Atlas users inside an organization.
You use teams to avoid assigning project roles user-by-user.
Example:
Team: Backend Developers
Members:
- Alice
- Bob
- Rajesh
Project: dev
Role:
- Project Data Access Read/Write
Project: prod
Role:
- Project Read Only
Teams are very useful for real companies because people join, move teams, or leave. Instead of changing every project manually, you update the team membership.
flowchart LR
U1[Alice] --> T[Backend Team]
U2[Bob] --> T
U3[Rajesh] --> T
T --> P1[dev project: Data Access Read/Write]
T --> P2[staging project: Read Only]
T --> P3[prod project: Read Only]
The Project Access Manager role can add or remove teams and manage team roles within a project. (MongoDB)
7. Atlas Project Roles
Project roles control what someone can do inside a project.
Common project roles:
| Project role | What it is for |
|---|---|
| Project Owner | Full project administration |
| Project Cluster Manager | Edit, pause, and resume clusters |
| Project Cluster Creator | Create clusters |
| Project Access Manager | Manage project users, teams, API keys, service accounts |
| Project Database Access Admin | Manage database users and custom database roles |
| Project Network Access Manager | Manage access lists, VPC peering, PrivateLink/private endpoint settings |
| Project Data Access Admin | Use Atlas UI Data Explorer with broad data permissions |
| Project Data Access Read/Write | Use Atlas UI Data Explorer to view/modify documents |
| Project Data Access Read Only | Use Atlas UI Data Explorer to view documents |
| Project Read Only | View project metadata, metrics, activity, users, roles |
A very important nuance: Project Data Access roles are for Atlas UI data access, especially Data Explorer. They do not allow reading or writing data through the Atlas Administration API. MongoDB states this explicitly for Data Access Admin and Data Access Read/Write roles. (MongoDB)
So:
Project Data Access Read/Write
✅ Can modify documents through Atlas UI Data Explorer
❌ Cannot use Atlas Admin API to query documents
8. Atlas Admin API Access
Atlas Admin API access is for automation.
Use it for:
Terraform
CI/CD
Platform engineering
Cluster provisioning
Database user management
Network access automation
Backup automation
Alert automation
Compliance reporting
Modern Atlas Admin API authentication supports:
Service accounts with OAuth 2.0 access tokens
Legacy API keys using HTTP Digest authentication
MongoDB recommends service accounts instead of API keys for the Atlas Administration API, and marks API keys as a legacy authentication method. (MongoDB)
Service Accounts
A service account is a machine identity for the Atlas Admin API.
It has:
Client ID
Client secret
Roles
Optional access list restrictions
Short-lived access tokens
Service accounts use OAuth 2.0 client credentials. They can be assigned roles like users, but they cannot log in to the Atlas UI and cannot access cluster data. Service account tokens are valid for one hour according to MongoDB’s docs. (MongoDB)
sequenceDiagram
participant CI as CI/CD Pipeline
participant OAuth as Atlas OAuth Token Endpoint
participant API as Atlas Admin API
participant Atlas as Atlas Project
CI->>OAuth: Send client ID + secret
OAuth-->>CI: Return short-lived access token
CI->>API: Call API with Bearer token
API->>API: Check service account role
API->>Atlas: Create/update Atlas resource
What Atlas API Can Do
Create clusters
Pause or resume clusters
Create database users
Update IP access list
Configure backups
Read project metadata
Manage alerts
Manage service accounts
What Atlas API Cannot Do
Read documents
Insert documents
Update documents
Delete documents
Run aggregation queries
Dump collection data
That last part matters a lot. Atlas Admin API can create a database user, but it does not magically become that database user. MongoDB explicitly says the Atlas Administration API does not provide access to data stored in clusters. (MongoDB)
9. Database Access: The Data Plane
To access data in MongoDB Atlas, a client needs three things:
1. Network path to the cluster
2. Valid database authentication
3. Database authorization role
Think of it as three locked doors:
flowchart LR
APP[Application / Compass / mongosh] --> N{Network allowed?}
N -->|No| DENY1[Connection blocked]
N -->|Yes| A{Database authentication valid?}
A -->|No| DENY2[Authentication failed]
A -->|Yes| Z{Role allows operation?}
Z -->|No| DENY3[Unauthorized]
Z -->|Yes| OK[Operation succeeds]
A correct username/password is not enough.
A correct database role is not enough.
You need all three.
10. Network Access
Before MongoDB even checks your database username/password, Atlas checks whether your client can reach the cluster.
Common network controls:
IP access list
Temporary IP access list entries
VPC/VNet peering
Private endpoints / PrivateLink / Private Service Connect
TLS
Firewall rules
Atlas network security starts restrictive: database connections are blocked unless you explicitly allow inbound access through a public IP access list entry, peering/private IPs, or private endpoints. Atlas also enforces mandatory TLS for database connections. (MongoDB)
IP Access List
An IP access list says:
Only these IP addresses or CIDR ranges can connect to this project’s clusters.
Example:
203.0.113.10/32 office IP
10.20.0.0/16 private network CIDR
Atlas project IP access list entries apply to all clusters in the project, and MongoDB documents that Atlas also supports temporary entries that expire within a configurable period. (MongoDB)
Private Endpoint
A private endpoint lets your application connect to Atlas without sending traffic over the public internet.
Recommended production pattern:
Application VPC/VNet
-> Private endpoint
-> Atlas cluster
MongoDB recommends private endpoints for staging and production projects because they reduce the network trust boundary and are usually easier than managing large IP allowlists at scale. (MongoDB)
Control Plane vs Data Plane IP Lists
There are two different IP-list concepts:
Atlas API/service account IP access list
Controls where Atlas API calls can come from.
Project cluster IP access list
Controls where database connections can come from.
MongoDB explicitly distinguishes API/programmatic access IP access lists from project data-plane IP access lists for cluster connections. (MongoDB)
11. Database Users
A database user is the identity used to connect to the MongoDB cluster.
Example connection string shape:
mongodb+srv://app_user:<password>@cluster-name.mongodb.net/app_db
The database user is usually created under:
Atlas UI -> Project -> Database & Network Access -> Database Users
Or by:
Atlas CLI
Atlas Administration API
Terraform
Atlas Kubernetes Operator
MongoDB says Atlas database users must be managed through Atlas-supported tools such as the Atlas UI, Atlas CLI, Atlas Administration API, or supported integrations; otherwise Atlas may roll back manual user modifications. (MongoDB)
12. Database User Authentication Methods
Atlas supports multiple database user authentication methods.
| Method | Best for |
|---|---|
| Password / SCRAM | Simple development and test setups |
| AWS IAM | Apps running in AWS, secret reduction |
| X.509 | Certificate-based authentication / mTLS style access |
| LDAP | Enterprise directory integration |
| OIDC / OAuth 2.0 | Modern identity federation for workforce/workload access |
MongoDB currently recommends service accounts for Atlas API access, while database authentication can use mechanisms such as SCRAM, AWS IAM, X.509, LDAP, and OIDC depending on your cluster and identity setup. MongoDB’s architecture guidance also says SCRAM is supported but recommends it primarily for development and test environments; for stronger production posture, prefer identity-based or certificate-based methods where appropriate. (MongoDB)
13. Database Authorization: Roles
Database authorization is role-based.
A database user gets one or more roles.
A role says:
On this database or collection,
allow these actions.
MongoDB roles grant privileges to perform actions on resources. A role can apply to a database and can grant access down to collection-level granularity. (MongoDB)
Common Database Roles
| Role | Scope | Meaning |
|---|---|---|
read | One database | Can read data |
readWrite | One database | Can read and write data |
dbAdmin | One database | Can perform database administration tasks |
readAnyDatabase | All databases | Can read across databases |
readWriteAnyDatabase | All databases | Can read/write across databases |
atlasAdmin | Broad Atlas database admin role | Powerful admin role; avoid for apps |
| Custom role | Database/collection/action-specific | Fine-grained least privilege |
For applications, avoid broad roles unless absolutely necessary.
Bad app user:
role: atlasAdmin
database: admin
Good app user:
role: readWrite
database: app_db
cluster scope: app-prod-cluster
Even better if the app only needs a subset of operations:
custom role:
db: app_db
collection: orders
actions:
- find
- insert
- update
14. Built-In Roles vs Custom Roles
Built-In Roles
Built-in roles are convenient and cover common cases:
read@app_db
readWrite@app_db
readAnyDatabase
readWriteAnyDatabase
clusterMonitor
backup
atlasAdmin
Atlas CLI role syntax uses this shape:
roleName@databaseName.collectionName
For example:
readWrite@app_db
read@reporting_db
The Atlas CLI docs describe the --role format as roleName[@dbName[.collection]], where the role can be built-in or custom, and database/collection are required for built-in roles. (MongoDB)
Custom Roles
Custom roles are for least privilege.
Use them when built-in roles are too broad.
Example use cases:
Analyst can read only reporting_db.daily_sales
Application can insert orders but not delete them
Support user can read limited customer metadata
ETL job can read source collection and write target collection
Atlas custom roles can be created when built-in roles do not match the desired privileges. Atlas applies custom roles together with built-in roles and specific privileges assigned to the database user. A single database user can have multiple custom roles. (MongoDB)
Important behavior: if multiple assigned roles grant different permissions for the same object, Atlas honors the highest permissions granted by any role. (MongoDB)
That means there is no useful “deny role” pattern like:
grant readWrite
then deny delete
Instead, create a smaller custom role that only grants what you need.
15. Project-Wide Database Users vs Cluster-Scoped Database Users
This is one of the biggest “oops” areas in Atlas.
By default, when you create a database user with Atlas built-in roles, Atlas adds that user to all clusters in the project. To narrow that, use Restrict Access to Specific Clusters or define more specific privileges/custom roles. (MongoDB)
Risky Design
Project: production
Clusters:
- prod-app-cluster
- prod-analytics-cluster
- prod-archive-cluster
Database user:
app_user with readWrite@app_db
Problem:
app_user may exist across all project clusters unless scoped.
Better Design
Project: production
Database user:
prod_app_user
role: readWrite@app_db
scope: prod-app-cluster only
Best Design for Many Teams
Use separate projects for different environments:
dev project
staging project
prod project
Then also scope users carefully inside each project.
16. Atlas UI Data Explorer vs Database Connection
Atlas UI Data Explorer is a feature inside Atlas.
It lets authorized Atlas users view or manipulate data through the Atlas UI.
That is different from connecting with:
mongosh
MongoDB Compass
Python driver
Node.js driver
Java driver
Go driver
Example
A developer has:
Atlas role:
Project Data Access Read Only
That means:
✅ They may view documents in Atlas UI Data Explorer.
❌ They cannot use that Atlas login as a MongoDB database username.
❌ They cannot query documents through Atlas Admin API.
For actual database connection, they need:
Database user:
dev_reader
Role:
read@app_db
17. Access Flow: Atlas UI Login
sequenceDiagram
participant User as Human User
participant AtlasLogin as Atlas Login / IdP
participant Atlas as Atlas UI
participant RBAC as Atlas RBAC
participant Project as Atlas Project
User->>AtlasLogin: Sign in
AtlasLogin-->>Atlas: Authenticated identity
Atlas->>RBAC: Check org/project roles
RBAC-->>Atlas: Allowed actions
Atlas->>Project: Show/manage permitted resources
Example:
Rajesh logs in to Atlas.
Atlas authenticates Rajesh.
Atlas checks his organization and project roles.
Atlas shows only what his roles allow.
If Rajesh has Project Read Only, he can view project metadata but cannot access Data Explorer or retrieve process/audit logs. (MongoDB)
18. Access Flow: Atlas Admin API
sequenceDiagram
participant Pipeline as CI/CD Pipeline
participant Token as OAuth Token Service
participant API as Atlas Admin API
participant RBAC as Atlas Project RBAC
participant Atlas as Atlas Resource
Pipeline->>Token: Request access token using service account
Token-->>Pipeline: Access token
Pipeline->>API: API call with token
API->>RBAC: Check service account role
RBAC-->>API: Allow or deny
API->>Atlas: Change Atlas configuration
Example:
CI/CD service account wants to create a database user.
It must have a project role that allows managing database access.
Good role:
Project Database Access Admin
Too broad:
Project Owner
The Project Database Access Admin role can manage database access and custom database roles, but it does not create clusters, access Data Explorer, or retrieve process/audit logs. (MongoDB)
19. Access Flow: Application Connecting to MongoDB
sequenceDiagram
participant App as Application
participant Net as Atlas Network Rules
participant Cluster as Atlas Cluster
participant Auth as Database Authentication
participant Authz as MongoDB Authorization
participant Data as Database / Collection
App->>Net: Connect from source IP/private endpoint
Net-->>App: Allowed or blocked
App->>Cluster: Start TLS connection
Cluster->>Auth: Validate database user credentials
Auth-->>Cluster: Authenticated
App->>Authz: Request operation: insert into app_db.orders
Authz-->>Cluster: Role allows insert?
Cluster->>Data: Execute operation if allowed
Example:
app_user connects from Kubernetes.
Atlas checks whether the Kubernetes egress IP or private endpoint is allowed.
MongoDB checks app_user credentials.
MongoDB checks whether app_user has insert permission on app_db.orders.
Only then does the insert succeed.
20. Hands-On Tutorial: Build a Secure Atlas Access Model
Let’s design a realistic setup.
Scenario
You have:
Company: ExampleCorp
Environment: dev, staging, prod
Application: ecommerce-api
Database: ecommerce
Collections:
- users
- orders
- payments
- products
Teams:
Platform Team
Backend Developers
Data Analysts
Auditors
CI/CD Automation
Production Application
Step 1: Create Organization and Projects
Recommended project layout:
Organization: ExampleCorp
Projects:
ecommerce-dev
ecommerce-staging
ecommerce-prod
Why separate projects?
Cleaner access control
Separate database users
Separate IP access lists
Separate backup settings
Separate alerts
Safer production boundary
Mermaid:
flowchart TD
ORG[ExampleCorp Organization]
ORG --> DEV[ecommerce-dev Project]
ORG --> STG[ecommerce-staging Project]
ORG --> PROD[ecommerce-prod Project]
DEV --> DEVCLUSTER[dev cluster]
STG --> STGCLUSTER[staging cluster]
PROD --> PRODCLUSTER[prod cluster]
Step 2: Create Atlas Teams
Suggested teams:
| Team | Purpose |
|---|---|
atlas-org-admins | Very small admin group |
platform-engineers | Cluster/network/backup operations |
backend-developers | Development team |
data-analysts | Reporting and analytics |
security-auditors | Read-only audit access |
support-readonly | Limited support access |
Step 3: Assign Atlas Roles
Suggested access matrix:
| Team | dev | staging | prod |
|---|---|---|---|
| atlas-org-admins | Project Owner | Project Owner | Project Owner |
| platform-engineers | Project Owner or Cluster Manager | Cluster Manager | Cluster Manager + Network Access Manager |
| backend-developers | Data Access Read/Write | Data Access Read Only | Project Read Only |
| data-analysts | Data Access Read Only | Data Access Read Only | Data Access Read Only, preferably limited |
| security-auditors | Project Read Only | Project Read Only | Project Read Only |
| support-readonly | Project Read Only | Project Read Only | Project Read Only |
Production hot take: do not give developers broad prod write access by default. That is how “I was just checking something” becomes a postmortem title.
Step 4: Configure Network Access
For dev:
Temporary IP access entries may be acceptable.
Developer office/VPN IPs may be allowed.
For staging:
Prefer private network access.
Allow CI/CD and staging app network only.
For prod:
Use private endpoints where possible.
Avoid 0.0.0.0/0.
Allow only production app network.
Allow only production CI/CD network for automation.
Bad prod setting:
0.0.0.0/0
Better prod setting:
Private endpoint from production VPC/VNet
CI/CD static egress IP only if needed
No developer laptop IPs
Step 5: Create Database Users
Use different database users for different purposes.
Bad pattern:
one_user_to_rule_them_all
role: atlasAdmin
used by app, developers, BI tools, cron jobs
Good pattern:
dev_app_user
staging_app_user
prod_app_user
prod_reporting_reader
prod_migration_user
prod_breakglass_admin
Example Users
| User | Role | Scope | Purpose |
|---|---|---|---|
dev_app_user | readWrite@ecommerce | dev cluster | Dev app |
staging_app_user | readWrite@ecommerce | staging cluster | Staging app |
prod_app_user | readWrite@ecommerce | prod app cluster only | Production app |
prod_reporting_reader | read@reporting | prod analytics cluster only | Reports |
prod_migration_user | Custom migration role | prod cluster, temporary | Migrations |
prod_breakglass_admin | Powerful admin role | prod, highly controlled | Emergency only |
21. Atlas CLI Examples
Create a Database User with Built-In Role
Example:
atlas dbusers create \
--username prod_app_user \
--password '<use-a-secret-manager-generated-password>' \
--role readWrite@ecommerce \
--scope prod-cluster \
--projectId '<PROJECT_ID>'
The Atlas CLI supports atlas dbusers create, accepts --username, --password, --role, --scope, and --projectId, and uses --scope to define the clusters the user can access. (MongoDB)
Create a Read-Only Reporting User
atlas dbusers create \
--username prod_reporting_reader \
--password '<use-a-secret-manager-generated-password>' \
--role read@reporting \
--scope prod-analytics-cluster \
--projectId '<PROJECT_ID>'
Create a Temporary Migration User
atlas dbusers create \
--username prod_migration_user \
--password '<temporary-secret>' \
--role readWrite@ecommerce \
--scope prod-cluster \
--deleteAfter '2026-06-16T00:00:00Z' \
--projectId '<PROJECT_ID>'
Atlas CLI supports --deleteAfter for a timestamp after which Atlas deletes the database user. (MongoDB)
22. Custom Role Example
Suppose an analytics job should only read:
reporting.daily_sales
It should not read:
reporting.customer_pii
reporting.payments_raw
Create a custom role conceptually like this:
Role: dailySalesReader
Resource:
db: reporting
collection: daily_sales
Actions:
find
Then assign:
User: analytics_job_user
Role: dailySalesReader
Flow:
flowchart LR
Job[Analytics Job] --> User[analytics_job_user]
User --> Role[dailySalesReader]
Role --> Resource[reporting.daily_sales]
Role --> Action[find only]
User -. denied .-> PII[reporting.customer_pii]
User -. denied .-> Payments[reporting.payments_raw]
Custom roles are ideal when built-in roles like read@reporting are too broad, because read@reporting would read the whole database, not just one collection.
23. Complete Access Design Example
Human Admin Access
Identity:
Alice, Platform Engineer
Atlas access:
Team: platform-engineers
Project role: Project Cluster Manager
Project role: Project Network Access Manager
Database access:
No default database user
Temporary admin database user only when needed
Why?
Alice can manage infrastructure.
Alice cannot casually browse production data.
Developer Access
Identity:
Backend developer
Atlas access:
dev: Project Data Access Read/Write
staging: Project Data Access Read Only
prod: Project Read Only
Database access:
dev database user only
Why?
Developers can move fast in dev.
Production data remains protected.
Production App Access
Identity:
ecommerce-api
Atlas access:
None
Database access:
prod_app_user
role: readWrite@ecommerce
scope: prod-cluster
network: private endpoint only
Why?
The app does not need Atlas UI or Atlas Admin API access.
It only needs database access.
CI/CD Access
Identity:
ci-cd-service-account
Atlas access:
Service account
Project Database Access Admin, if it manages DB users
Project Cluster Manager, if it updates clusters
Project Network Access Manager, if it updates access lists
Database access:
Usually none
Why?
CI/CD manages Atlas configuration.
It should not read customer data unless specifically required.
Analyst Access
Identity:
Data analyst
Atlas access:
Possibly Project Data Access Read Only
Database access:
reporting_reader
role: read@reporting
or custom collection-level role
Why?
Analysts read curated reporting data.
They should not read operational or sensitive collections by default.
24. Authorization Decision Tree
Use this when someone asks: “What access should I give?”
flowchart TD
START[User or app needs access] --> Q1{Need to manage Atlas resources?}
Q1 -->|Yes| ATLAS[Grant Atlas org/project role]
Q1 -->|No| Q2{Need to read/write database data?}
ATLAS --> Q1A{Human or machine?}
Q1A -->|Human| USER[Atlas user or team]
Q1A -->|Machine| SA[Service account preferred]
USER --> ROLE1[Assign least-privilege project/org role]
SA --> ROLE2[Assign least-privilege service account role]
Q2 -->|Yes| DBUSER[Create database user]
Q2 -->|No| NOACCESS[No access needed]
DBUSER --> Q3{What data scope?}
Q3 -->|Whole database read| READ[read@db]
Q3 -->|Whole database read/write| RW[readWrite@db]
Q3 -->|One collection/actions only| CUSTOM[Custom DB role]
Q3 -->|Admin tasks| ADMIN[Specific admin role, avoid broad admin]
READ --> NET[Configure network access]
RW --> NET
CUSTOM --> NET
ADMIN --> NET
NET --> TEST[Test with actual operation]
25. Common Mistakes
Mistake 1: Confusing Atlas User with Database User
Wrong assumption:
“I can log in to Atlas, so I can connect with mongosh.”
Reality:
Atlas login is for Atlas UI.
Database connection needs database credentials.
Mistake 2: Giving Apps Atlas Admin API Access
Most apps do not need this:
Atlas service account
Project Owner
Most apps need this:
Database user
readWrite@app_db
Network access from app environment
Mistake 3: Using One Database User Everywhere
Bad:
same username/password in dev, staging, prod
Good:
dev_app_user
staging_app_user
prod_app_user
Mistake 4: Leaving Database User Unscoped
Bad:
User exists across all clusters in the project
Good:
Restrict Access to Specific Clusters
Mistake 5: Using atlasAdmin for Applications
Bad:
Application role: atlasAdmin
Good:
Application role: readWrite@app_db
Best:
Custom role with only required actions
Mistake 6: Allowing Public Internet Too Broadly
Bad:
0.0.0.0/0
Good:
Private endpoint
Static egress IP
VPN CIDR
Temporary IP access entry for short-lived work
Mistake 7: Assuming Project Read Only Means Data Read Only
Project Read Only is mostly Atlas control-plane visibility. It does not grant Data Explorer access. MongoDB’s docs say Project Read Only grants view-only access to project control plane metadata but not Data Explorer access. (MongoDB)
26. Troubleshooting Guide
Error: “Authentication failed”
Likely causes:
Wrong username
Wrong password
Wrong authSource
User deleted or expired
Wrong authentication mechanism
SCRAM vs AWS IAM vs X.509 mismatch
Password contains special characters not URL-encoded
Check:
Is the database user present in Atlas?
Is the password correct?
Is the connection string correct?
Is authSource correct?
For AWS IAM, is authMechanism=MONGODB-AWS?
For X.509, does certificate subject match expected user?
Error: “not authorized on db to execute command”
Likely causes:
User authenticated successfully
But role does not allow the attempted operation
Example:
User has read@app_db
Operation is insert into app_db.orders
Result: unauthorized
Fix:
Grant readWrite@app_db
or create a custom role with insert on app_db.orders
Error: “connection timed out”
Likely causes:
IP not allowed
Private endpoint not configured correctly
Firewall issue
DNS issue
Wrong connection string
Cluster paused
Check:
Project IP access list
Private endpoint status
VPC/VNet routing
Security groups / firewall rules
Cluster status
DNS resolution
Error: “user works in dev but not prod”
Likely causes:
Different project
Different database user
Different network access
Different cluster scope
Different password
Different role
Fix:
Compare dev and prod:
project role
database user role
cluster scope
network access
connection string
27. Recommended Production Security Model
Use this as your production baseline.
Atlas Organization
Very few Organization Owners
SSO / federated authentication enabled
MFA enforced
Separate teams for admins, developers, auditors
No shared human accounts
Atlas Projects
Separate dev, staging, prod projects
Separate database users per environment
Separate network rules per environment
Separate service accounts per automation pipeline
Atlas API
Use service accounts instead of legacy API keys
Grant least-privilege project roles
Restrict API access to trusted CI/CD IPs
Rotate secrets
Store client secrets in a secret manager
Do not use API access for app data queries
Database Users
One database user per app/service/job
No shared superuser
No atlasAdmin for app runtime
Use readWrite only on required database
Use custom roles for sensitive collections
Use temporary users for short-lived migration/admin work
Restrict users to specific clusters
Network
Use private endpoints for staging/prod
Avoid 0.0.0.0/0
Use temporary IP entries for emergency work
Keep app egress IPs stable
Separate control-plane API IP lists from data-plane cluster access lists
Operations
Review users and roles regularly
Remove unused database users
Rotate app secrets
Monitor Activity Feed
Audit database access where required
Use break-glass access with approval and expiry
28. The Best Mental Model
Remember this:
Atlas user/team/service account/API key
-> controls Atlas management actions
Database user
-> controls MongoDB data actions
Network access
-> controls who can reach the cluster
Database roles
-> control what authenticated clients can do inside MongoDB
One more diagram to tattoo on the inside of your eyelids:
flowchart TD
A[Need Access] --> B{Atlas Management or Database Data?}
B -->|Atlas Management| C[Atlas Identity]
C --> C1[Human: Atlas User / Team]
C --> C2[Machine: Service Account]
C1 --> C3[Org Role / Project Role]
C2 --> C3
C3 --> C4[Manage Atlas Resources]
B -->|Database Data| D[Database Identity]
D --> D1[Database User]
D1 --> D2[Authentication Method]
D2 --> D3[SCRAM / AWS IAM / X.509 / LDAP / OIDC]
D3 --> D4[Database Roles]
D4 --> D5[read / readWrite / custom privileges]
D5 --> D6[Read or Write Documents]
D --> E[Network Access]
E --> E1[IP Access List / Private Endpoint / Peering]
29. Final Cheat Sheet
| Need | Use this identity | Use this permission |
|---|---|---|
| Log in to Atlas UI | Atlas user | Org/project role |
| Assign users to projects | Atlas user or team | Project Access Manager / Project Owner |
| Automate cluster creation | Service account | Project Cluster Creator / Project Owner as needed |
| Automate DB user creation | Service account | Project Database Access Admin |
| Connect app to MongoDB | Database user | readWrite@app_db or custom role |
| Read reports only | Database user | read@reporting or custom role |
| View documents in Atlas UI | Atlas user/team | Project Data Access Read Only |
| Modify documents in Atlas UI | Atlas user/team | Project Data Access Read/Write |
| Query documents from app/API/driver | Database user | MongoDB database role |
| Restrict source network | Network access | IP list/private endpoint/VPC peering |
| Emergency admin | Temporary database user | Short-lived admin role, audited |
30. One-Sentence Summary
MongoDB Atlas authentication and authorization is best understood as three gates:
Atlas RBAC controls who manages Atlas.
Network access controls who can reach the cluster.
Database RBAC controls who can read/write MongoDB data.
Keep those gates separate, grant the smallest useful permission at each gate, and your Atlas security model becomes clean, scalable, and production-grade.
