An Amazon DocumentDB cluster holds application documents behind two separate doors, the AWS control plane that can copy, share and restore the whole cluster and the database users who read and write its collections, and both need deliberate configuration. DocumentDB is a managed document database that works with MongoDB API drivers and tools, with AWS running the storage, instances and patching. Users, roles, IAM authentication, the tls parameter, audit logging, encryption keys and snapshot sharing are customer-side settings. This guide covers each of them, with a hardening baseline and the misconfigurations to check for. It is for database administrators, application developers and cloud security reviewers. Principles common to all databases are in the Database Security Guide; this page goes into the DocumentDB settings themselves.
This is an independent guide from NHI Mgmt Group, based on AWS's public documentation for Amazon DocumentDB as of November 2026. It is not sponsored or reviewed by AWS. Product features change, so confirm settings against AWS's current documentation.
Key takeaways
- The primary user is root; keep it for administration. The primary user and
serviceadminalways hold therootrole and cannot be deleted, so applications should connect as their own least-privilege users. - Use IAM authentication where the engine supports it. On instance-based clusters running version 5.0, users defined in
$externalwith theMONGODB-AWSmechanism authenticate with temporary AWS credentials instead of stored passwords. - Keep the
tlsparameter attls1.2+or stronger. TLS is on by default for new clusters; a custom parameter group lets you settls1.2+,tls1.3+orfips-140-3, applied after an instance reboot. - Auditing takes two steps. Set
audit_logsin a custom cluster parameter group and export theauditlog type to CloudWatch Logs; without both, no audit events arrive. - Encryption and snapshot sharing are decided early. Encryption at rest is chosen at cluster creation, and encrypted snapshots can be shared only with named accounts using a customer managed key.
How identity and access work in Amazon DocumentDB
There are two layers. IAM governs the rds: control-plane API that DocumentDB uses (create, modify, snapshot, restore, delete). Inside the cluster, database users authenticate and are authorised by role-based access control (RBAC). Users and roles are stored and authenticated in the admin database, and IAM-authenticated users in the $external database.
| Authentication method | Where users live | Credential | Best fit |
|---|---|---|---|
| Password (SCRAM) | admin | User name and password, ideally held in Secrets Manager | Primary user, tools and clients that cannot use IAM |
IAM authentication (MONGODB-AWS) | $external, named by IAM user or role ARN | Temporary AWS credentials from the workload's role | Applications on EC2, Lambda, Fargate and EKS against version 5.0 instance-based clusters |
Authentication and authorisation are separate: a user can connect and still receive "Authorization failure" (code 13) on a database where it holds no role. With IAM authentication, temporary credentials are used only to establish the connection, so connections stay up when the IAM credentials later rotate or expire.
Built-in and user-defined roles
| Role | Scope | Grants | Typical holder |
|---|---|---|---|
read | One database | find, listCollections, listIndexes, change streams | Reporting and read-only services |
readWrite | One database | read plus insert, update, remove, create and drop collections and indexes | Application service users |
dbAdmin, dbOwner | One database | Administration such as collMod and dropDatabase (dbOwner adds readWrite) | Schema owners via pipeline |
readAnyDatabase, readWriteAnyDatabase | Cluster | Read or read and write on every database | Rarely needed; avoid for applications |
userAdminAnyDatabase | Cluster | createUser, grantRole, revokeRole, dropUser | Database administrators only |
clusterAdmin, hostManager | Cluster | Cluster management, killop, auditConfigure | Database administrators only |
backup, restore | Cluster | Backup access; restore includes write and user management actions | Backup tooling roles |
root | Cluster | All of the above | Primary user and serviceadmin only |
User-defined roles, created with createRole, can grant specific actions such as find, insert, update and remove on a single collection. This is the way to give a service access to one collection rather than a whole database. Documented limits are 1,000 users per cluster, 1,000 roles per user, 100 user-defined roles and 100 resources per privilege. AWS also notes that users created before 26 March 2020 were given dbAdminAnyDatabase, readWriteAnyDatabase and clusterAdmin; review older clusters and reduce those grants.
Admin roles and privileged access
Privilege exists in both layers. Inside the database, root, userAdminAnyDatabase and clusterAdmin control everything. In the control plane, the actions that copy, share or remove the cluster are just as powerful.
| Control-plane action | Effect | Who should hold it |
|---|---|---|
| ModifyDBCluster (including master user password) | Resets the primary user's password, changes parameter groups and log exports | Pipeline role; alert on password changes |
| ModifyDBClusterParameterGroup | Changes tls and audit_logs | Pipeline role; alert on use |
| ModifyDBClusterSnapshotAttribute | Shares a manual snapshot with other accounts, or makes an unencrypted one public | Backup administrators; deny the all value through an SCP |
| CopyDBClusterSnapshot, RestoreDBClusterFromSnapshot | Creates a copy of production data with new settings | Backup administrators; alert on use |
| DeleteDBCluster, DeleteDBClusterSnapshot | Data loss (T1485) | Pipeline role, with deletion protection on |
- Primary user handling: store the primary user's password in Secrets Manager, rotate it, and use it only to create users and roles. The primary user authenticates by password; IAM identities are created as separate users.
- Human administrators: give DBAs a named database user with
userAdminAnyDatabaseor a custom admin role, reached from a bastion or session-managed host, instead of sharing the primary user. See the AWS IAM Identity Center Guide for the AWS side. - Organisation guardrails: SCPs can deny snapshot attribute changes and cluster deletion outside designated roles. See the AWS Organizations and SCPs Guide.
Integrations, API tokens and service accounts
IAM authentication for applications
- Connect as the primary user and switch to the
$externaldatabase. - Create a user named by the workload's IAM role ARN with
mechanisms: ["MONGODB-AWS"]and only the roles it needs, for examplereadWriteon one database or a collection-scoped custom role. - Connect with
authSource=$externalandauthMechanism=MONGODB-AWS, with no credentials in the URI. On EC2, Lambda and Fargate the driver reads the role's temporary credentials from the environment; on EKS it usesAWS_WEB_IDENTITY_TOKEN_FILEandAWS_ROLE_ARN. - Use drivers that support the mechanism: AWS notes Node.js drivers need version 6.13.1 or later (including tools built on them such as mongosh), and Python needs
pymongo[aws].
Authentication calls AWS STS, so connection storms can be throttled; use connection pooling. The StsGetCallerIdentityCalls metric shows the call rate, and audit logs can be filtered with { $.param.mechanism = "MONGODB-AWS" }. Prefer role-based credentials over embedding IAM access keys in a URI, which only moves the static secret. See the AWS Access Keys Security Guide.
Password users
For clients that cannot use IAM, create one user per application with a scoped role and keep the password in AWS Secrets Manager, retrieved at runtime and rotated on a schedule. Never place passwords in connection strings in source code or container images, a common route to T1552.001 credential exposure and then T1078.004 misuse. See the AWS Secrets Manager Guide.
Change streams and downstream consumers
Change streams feed search indexes, caches and event pipelines. The read role includes change streams on its database, and modifyChangeStreams controls enabling them. Give each consumer its own user scoped to the databases it streams, so a pipeline credential cannot read unrelated collections.
Logging and detection
DocumentDB has two complementary logs. CloudTrail is always on for control-plane operations on clusters, instances and snapshots. DocumentDB auditing is opt-in and records operations inside the cluster. See the AWS CloudTrail Guide.
audit_logs value | Records | When to use |
|---|---|---|
ddl | Database and collection changes, index changes, authentication and authorisation checks, user management | Every production cluster (minimum) |
dml_read | find, count, distinct, aggregation reads | Clusters holding personal or regulated data, ideally with DML filters |
dml_write | insert, update, delete, bulkWrite | Clusters where integrity of records matters |
all | All of the above | Highest-sensitivity clusters |
none | Nothing (default) | Replace on every production cluster |
Values combine as a comma-separated lowercase list, for example ddl,dml_write. After setting the parameter, export the audit log type with ModifyDBCluster; events appear in /aws/docdb/clusterName/audit. DML filters, set with setAuditConfig by a user holding auditConfigure, can limit volume by command, user or namespace. DML parameter values are truncated at 1 KB and TTL deletes are not audited.
| Signal | Source | Why it matters |
|---|---|---|
ModifyDBClusterSnapshotAttribute adding an account or all | CloudTrail | Data shared outside the organisation (T1537) |
Parameter group change to tls or audit_logs | CloudTrail | Encryption or auditing changed |
| Primary user password reset through ModifyDBCluster | CloudTrail | Possible takeover of the root database user |
| createUser, grantRole or grantRolesToUser outside change windows | DocumentDB audit (ddl) | New or escalated database access |
| Repeated authentication failures | DocumentDB audit (ddl) | Password guessing or a misconfigured client |
| Large find or aggregate volume by an unusual user | DocumentDB audit (dml_read) | Bulk data collection (T1530) |
AWS Security Hub CSPM includes DocumentDB.1 (encrypted at rest), DocumentDB.2 (adequate backup retention), DocumentDB.3 (manual snapshots not public, critical), DocumentDB.4 (audit logs published to CloudWatch Logs), DocumentDB.5 (deletion protection) and DocumentDB.6 (encrypted in transit). See the AWS Security Hub Guide.
Metrics that show the controls are working
- Control pass rate: percentage of clusters passing DocumentDB.1 to DocumentDB.6.
- Application users on IAM: share of application users defined in
$externalon version 5.0 clusters. - Over-privileged users: number of non-admin users holding any cluster-scoped role.
- Snapshot sharing: number of manual snapshots shared with accounts outside the organisation, each with an owner.
- Audit coverage: percentage of production clusters with
audit_logsset and the audit log type exported.
Hardening baseline
The sequence below is NHI Mgmt Group guidance, not a vendor requirement; adjust it to your environment.
- Custom parameter groups: the default cluster parameter group cannot be modified, so create a custom group for every cluster before changing
tlsoraudit_logs. - TLS: set
tlstotls1.2+(ortls1.3+where all clients support it, orfips-140-3where FIPS is required and the Region supports it). It is a static parameter, so reboot each instance to apply it. Distribute the AWS CA bundle to clients and connect withtls=true. - Encryption at rest: create clusters with storage encryption on (the console default; add
--storage-encryptedin the CLI) and a customer managed symmetric KMS key for sensitive data. The key cannot be changed later. To encrypt an existing cluster, snapshot it and restore into a new encrypted cluster. Protect the key: if DocumentDB loses access for more than 7 days, the cluster can only be recovered from a snapshot that still needs the original key. See the AWS KMS Security Guide. - Users and roles: one user per application with database or collection-scoped roles; review users created before 26 March 2020; keep the primary user for administration.
- IAM authentication: on version 5.0 instance-based clusters, move AWS-hosted applications to
MONGODB-AWSusers in$external. - Network: place clusters in private subnets with security groups that allow port 27017 only from application security groups. See the Amazon VPC Security Guide.
- Auditing: set
audit_logsto at leastddland export the audit log type. - Snapshots and recovery: turn on deletion protection, set backup retention to meet recovery needs, encrypt with customer managed keys and share manual snapshots only with named accounts.
Testing and rollback: apply parameter group changes to a staging cluster first and reboot one replica before the primary, so client compatibility problems with stricter TLS show up on a single instance. Revert by restoring the previous parameter value and rebooting. Small teams can begin with TLS, encryption, deletion protection and per-application users; larger estates add IAM authentication, DML auditing for regulated data and SCP guardrails on snapshot sharing.
Common misconfigurations
- Applications using the primary user: every service connects as the
root-holding primary user, so any leaked connection string grants full control. - Legacy broad grants: users created before 26 March 2020 still carrying cluster-wide read, write and admin roles.
- Audit parameter set but not exported:
audit_logsconfigured without exporting the audit log type, or the reverse, so nothing reaches CloudWatch Logs. - Parameter changes waiting for a reboot:
tlschanged in the parameter group but instances never rebooted, leaving the old setting live. - Snapshots shared too widely: unencrypted manual snapshots marked public, or encrypted ones shared with accounts no longer in use. DocumentDB.3 flags public snapshots.
- Passwords in connection strings: credentials embedded in code, images or environment files rather than retrieved from Secrets Manager or replaced with IAM authentication.
Framework mapping
| Control area | NIST SP 800-53 Rev 5 | ATT&CK technique addressed |
|---|---|---|
| RBAC, scoped users, primary user restriction | AC-3, AC-6 | T1078.004 Cloud Accounts |
| IAM authentication and Secrets Manager | IA-5 | T1552.001 Credentials In Files |
| TLS parameter and private subnets | SC-8, SC-7 | T1190 Exploit Public-Facing Application |
| Encryption at rest with customer managed keys | SC-28, SC-12 | T1530 Data from Cloud Storage |
| Snapshot sharing controls | AC-3 | T1537 Transfer Data to Cloud Account |
| Audit logs and CloudTrail | AU-2, AU-12 | Detection for all of the above |
| Backups and deletion protection | CP-9 | T1485 Data Destruction |
Practitioner checklist
- Every cluster uses a custom parameter group with
tlsattls1.2+or stronger, and instances have been rebooted. - Clusters are encrypted at rest, with customer managed keys for sensitive data and key policies under change control.
- Applications connect as their own users with database or collection-scoped roles, never as the primary user.
- AWS-hosted applications on version 5.0 clusters use
MONGODB-AWSusers in$external. - Remaining passwords live in Secrets Manager and are rotated.
audit_logsis set to at leastddland the audit log type is exported to CloudWatch Logs.- Deletion protection is on and backup retention meets recovery objectives.
- No manual snapshot is public; shared snapshots go only to named accounts with a customer managed key.
- CloudTrail alerts cover snapshot attribute, parameter group and primary password changes.
Standards and references
- AWS: Database access using role-based access control in Amazon DocumentDB
- AWS: Authentication using IAM identity in Amazon DocumentDB
- AWS: Encrypting data in transit in Amazon DocumentDB
- AWS: Encrypting Amazon DocumentDB data at rest
- AWS: Auditing Amazon DocumentDB events
- AWS: Sharing Amazon DocumentDB cluster snapshots
- AWS: Security Hub controls for Amazon DocumentDB
- NIST: SP 800-53 Rev. 5 Security and Privacy Controls
Related NHI Mgmt Group resources: Database Security Guide, AWS Secrets Manager Guide, AWS KMS Security Guide, Amazon ElastiCache and MemoryDB Security, Data Security Guide.