Introduction
If you've ever tried connecting Amazon DocumentDB to MongoDB Compass with a non-root user, you've likely hit a frustrating authorization failure. Meanwhile, the root user connects without any issues. This isn't a misconfiguration on your end — it's a fundamental limitation of Amazon DocumentDB.
This blog post walks through the exact problem, what we discovered during our POC, and the recommended setup for teams working with DocumentDB in production.
What is Amazon DocumentDB?
Amazon DocumentDB is a fully managed, MongoDB-compatible document database service from AWS. It mimics the MongoDB API but is NOT standard MongoDB. AWS built DocumentDB with intentional restrictions, especially around role-based access control (RBAC) and cluster-level commands.
Step 1: Setting Up the EC2 to DocumentDB Connection
The first step is connecting your EC2 instance to the DocumentDB cluster. AWS provides a built-in connectivity setup wizard in the DocumentDB console that automatically configures the required security groups between your EC2 instance and the cluster.
Screenshot: AWS DocumentDB console — successful connection setup between DocumentDB cluster and EC2 instance, with all security group rules created automatically.
As seen above, the wizard creates and attaches security groups to both the DocumentDB cluster and the EC2 instance, and removes default rules - resulting in a locked-down, VPC-internal connection.
Step 2: Download the SSL Certificate on EC2
DocumentDB requires TLS for all connections. You need to download the AWS global trust bundle (global-bundle.pem) on your EC2 instance before connecting.
sudo wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
Screenshot: Downloading the global-bundle.pem SSL certificate from AWS truststore on the EC2 instance.
Step 3: Install MongoDB Shell (mongosh)
Install mongosh on the EC2 instance to connect to DocumentDB from the command line.
sudo apt install -y mongodb-mongosh
Screenshot: Installing mongodb-mongosh (version 2.8.1) on the EC2 Ubuntu instance.
Step 4: Connect to DocumentDB via mongosh
Connect to the DocumentDB cluster using the root/admin user credentials with TLS enabled:
mongosh datablogs.cta8ayagibis.us-east-1.docdb.amazonaws.com:27017 \
--tls --tlsCAFile global-bundle.pem --retryWrites=false \
--username blogsuser --password 'yourpassword'
Screenshot: Successfully connecting to DocumentDB using mongosh with the root (blogsuser) credentials. MongoDB 5.0.0, Mongosh 2.8.1.
Step 5: Review Existing Users
After connecting, run show users to see the current users in the admin database:
use admin
show users;
Screenshot: CloudShell view showing existing users — serviceadmin and blogsuser both have the root role on the admin database.
Screenshot: Updated user list showing three users — serviceadmin (root), blogsuser (root), and bpitpadbuser (readWrite on bpitpadatabase).
Note that bpitpadbuser has readWrite on bpitpadatabase - a typical non-root restricted role. This user connects fine via mongosh but fails in MongoDB Compass, as we discovered during our testing.
Step 6: Testing Non-Root User Connection
We tested connecting with the restricted bpitpadbuser credentials to validate the behavior:
mongosh datablogs.cta8ayagibis.us-east-1.docdb.amazonaws.com:27017 \
--tls --tlsCAFile global-bundle.pem --retryWrites=false \
--username bpitpadbuser --password 'yourpassword'
Screenshot: bpitpadbuser successfully connecting to DocumentDB via mongosh. The shell connects fine — but this same user fails in MongoDB Compass.
The Core Problem: Why Compass Fails for Non-Root Users
The mongo shell and MongoDB Compass behave very differently on startup. When Compass connects, it automatically runs these cluster-level commands:
db.adminCommand({ listDatabases: 1 })
db.adminCommand({ connectionStatus: 1 })
db.runCommand({ getCmdLineOpts: 1 })
In DocumentDB 5.0, these cluster-level commands are only permitted for users with the root role. Non-root users — even with readWriteAnyDatabase or dbAdminAnyDatabase — are silently blocked, causing Compass to throw an authorization error.
The mongo shell does NOT run these commands automatically, which is why non-root users connect fine in the shell but fail in Compass.
Test Results Summary
Connection Method | Root User | readWrite User | readWriteAnyDatabase |
EC2 mongosh shell | Works | Works | Works |
MongoDB Compass via SSH | Works | Fails | Fails |
Application backend | Works | Works | Works |
Supported Roles in DocumentDB 5.0
Role | Scope | Works in Compass |
root | admin db | Yes |
readWriteAnyDatabase | admin db | No |
dbAdminAnyDatabase | admin db | No |
readWrite | specific db | No |
dbOwner | specific db | No |
Recommended Production Setup
Since DocumentDB forces root for Compass, the best approach is to separate users by purpose and secure access at the network and infrastructure level.
Two-User Pattern
// Compass admin user — root role for visual tooling
use admin
db.createUser({
user: 'compass-admin',
pwd: 'StrongPassword123',
roles: [{ role: 'root', db: 'admin' }]
});
// Application user — restricted, used by backend code only
db.createUser({
user: 'app-user',
pwd: 'AppPassword123',
roles: [{ role: 'readWrite', db: 'yourdatabase' }]
});
Security Checklist
Use root role only for Compass / admin tooling — never in application code
Restrict EC2 bastion Security Group to your specific IP only
Never open port 27017 publicly — DocumentDB is VPC-only by design
Always connect via SSH tunnel through the bastion EC2
Rotate the Compass password regularly
Use AWS CloudTrail to audit all database access
Use the restricted app-user in your backend — minimal privilege only
Conclusion
The root-only behavior in MongoDB Compass with DocumentDB is not a bug you can fix — it is an intentional AWS architectural decision. Understanding this early saves hours of debugging.
User | Role | Use For |
compass-admin | root | MongoDB Compass / admin tooling |
app-user | readWrite on specific db | Backend application code |
report-user | read on specific db | Read-only reporting / analytics |
Use root for Compass, secure at the network level, and use minimal-privilege users for your application. This is the standard and accepted pattern for teams running Amazon DocumentDB in production.
The root-only Compass behavior is consistent across all DocumentDB versions (4.0, 5.0, 8.0).
0 Comments