Built-In Roles

MongoDB grants access to data and commands through role-based authorization. MongoDB provides built-in roles that grant the different levels of access commonly needed in a database system.

A role grants privileges to perform sets of actions on defined resources. A role applies to the database on which it is defined and can grant access down to a collection level of granularity.

Each built-in role defines access at the database level for all non-system collections in the role's database and at the collection level for all system collections.

System collections include those in:

<database>.system.* namespace
local.replset.* replica set namespace

Non-system collections are those not in namespaces in the previous list.

MongoDB Atlas database users have different built-in roles than self-hosted deployment users. However, MongoDB builds the built-in roles for each type of deployment from the same set of privilege actions.

Use the selector at the top of the page to choose your deployment type and see the available built-in roles.

MongoDB Atlas Built-In Roles

This section describes the MongoDB Atlas built-in roles and the MongoDB Roles they represent.

Create database users and assign built-in roles in the MongoDB Atlas user interface. To learn more, see Add Database Users.

To learn more about common commands that MongoDB Atlas does not support with the current MongoDB Atlas user privileges, see Unsupported Commands.

Atlas-Only Roles

The following roles are available only in MongoDB Atlas and have no corresponding self-managed MongoDB role.

killOpSession

Provides the ability to view and kill active operations, and manage sessions.

On the cluster as a whole, provides the following actions:

autoCompact

Provides the ability to run the autoCompact command to enable background compaction.

Background compaction periodically iterates through available files and releases unneeded disk space to the operating system. To learn more about authentication requirements for autoCompact, see Required Privileges.

On the cluster as a whole, provides the following action:

compact

manageShardBalancer

Provides the ability to manage shard balancer settings, including range size and balancer status. To learn more about shard balancing, see Sharded Cluster Balancer.

On the config.settings collection, provides the following actions:

Protected MongoDB Database Namespaces

Avoid writing to the admin, local, and config databases, or any database prefixed with __mdb_internal_. MongoDB Atlas manages multiple collections in these databases. To learn more, see Internal Databases and System Collections.

atlasAdmin has the update privilege on the config.settings collection to manage the balancer.

Built-in Roles and Inherited Privileges

In the following table, indicates that the operation also supports timeseries collections.

MongoDB Atlas Built-in Role	MongoDB Role	Inherited Roles or Privilege Actions
`Atlas admin`	`atlasAdmin`	This role allows you to use `setQuerySettings`, `removeQuerySettings`, and `$querySettings`. `analyzeShardKey` `autoCompact` backup `checkMetadataConsistency` `cleanupOrphaned` `clearJumboFlag` clusterMonitor `compact` dbAdminAnyDatabase enableSharding `flushRouterConfig` `killAnyCursor` `moveChunk` `querySettings` readWriteAnyDatabase `refineCollectionShardKey` `reshardCollection` `shardedDataDistribution` `splitChunk` `viewRole`
`backup`	`backup`	backup
`clusterMonitor`	`clusterMonitor`	clusterMonitor
`dbAdmin`	`dbAdmin`	dbAdmin
`dbAdminAnyDatabase`	`dbAdminAnyDatabase`	dbAdminAnyDatabase
`enableSharding`	`enableSharding`	enableSharding
`read`	`read`	read
`readWrite`	`readWrite`	readWrite
`readWriteAnyDatabase`	`readWriteAnyDatabase`	readWriteAnyDatabase
`readAnyDatabase`	`readAnyDatabase`	readAnyDatabase
`killOpSession`		`killOpSession`
`autoCompact`		`autoCompact`
`manageShardBalancer`		`manageShardBalancer`

MongoDB Built-In Role Descriptions

The following are the MongoDB built-in roles used by MongoDB Atlas built-in roles.

MongoDB Role	Description
`backup`	Provides minimal privileges needed for backing up data. This role provides sufficient privileges to use the MongoDB Cloud Manager backup agent, Ops Manager backup agent, or to use `mongodump` to back up an entire `mongod` instance.
`clusterMonitor`	Provides read-only access to monitoring tools, such as the MongoDB Cloud Manager and Ops Manager monitoring agent.
`dbAdmin`	Provides the ability to perform administrative tasks such as schema-related tasks, indexing, and gathering statistics. This role does not grant privileges for user and role management.
`dbAdminAnyDatabase`	Provides the same privileges as `dbAdmin` on all databases except `local` and `config`. The role also provides the `listDatabases` action on the cluster as a whole.
`enableSharding`	Provides the ability to enable sharding for a collection and modify existing shard keys.
`read`	Provides read access to all non-system collections and the `system.js` collection.
`readAnyDatabase`	Provides the same read-only privileges as `read` on all databases except `local` and `config`. The role also provides the `listDatabases` action on the cluster as a whole. This role grants permissions on database resources, not cluster administrative resources.
`readWrite`	Provides all privileges of the `read` role plus the ability to modify data on all non-system collections and the `system.js` collection.
`readWriteAnyDatabase`	Provides the same privileges as `readWrite` on all databases except `local` and `config`. The role also provides: the `listDatabases` action on the cluster as a whole the `compactStructuredEncryptionData` action This role grants permissions on database resources, not cluster administrative resources.

Learn More

If built-in roles do not meet your requirements, create user-defined roles. For more information, see Configure Custom Database Roles.

Self-Managed Deployment Built-In Roles

MongoDB provides the following built-in roles in self-managed deployments.

To view the privileges for a built-in role, run the rolesInfo command with the showPrivileges and showBuiltinRoles fields both set to true. The following command shows the privileges for the readWrite role:

db.getRole("readWrite", { showPrivileges: true, showBuiltinRoles: true } )

{
   db: 'test',
   role: 'readWrite',
   roles: [],
   privileges: [
      {
         resource: { db: 'test', collection: '' },
         actions: [
            'changeStream',
            'cleanupStructuredEncryptionData',
            'collStats',
            'compactStructuredEncryptionData',
            'convertToCapped',
            'createCollection',
            'createIndex',
            'createSearchIndexes',
            'dbHash',
            'dbStats',
            'dropCollection',
            'dropIndex',
            'dropSearchIndex',
            'find',
            'insert',
            'killCursors',
            'listCollections',
            'listIndexes',
            'listSearchIndexes',
            'updateSearchIndex',
            'planCacheRead',
            'performRawDataOperations',
            'remove',
            'renameCollectionSameDB',
            'update'
         ]
      },
      {
         resource: { db: 'test', collection: 'system.js' },
         actions: [
            'changeStream',
            'cleanupStructuredEncryptionData',
            'collStats',
            'compactStructuredEncryptionData',
            'convertToCapped',
            'createCollection',
            'createIndex',
            'createSearchIndexes',
            'dbHash',
            'dbStats',
            'dropCollection',
            'dropIndex',
            'dropSearchIndex',
            'find',
            'insert',
            'killCursors',
            'listCollections',
            'listIndexes',
            'listSearchIndexes',
            'updateSearchIndex',
            'planCacheRead',
            'performRawDataOperations',
            'remove',
            'renameCollectionSameDB',
            'update'
         ]
      }
   ],
   inheritedRoles: [],
   inheritedPrivileges: [
      {
         resource: { db: 'test', collection: '' },
         actions: [
            'changeStream',
            'cleanupStructuredEncryptionData',
            'collStats',
            'compactStructuredEncryptionData',
            'convertToCapped',
            'createCollection',
            'createIndex',
            'createSearchIndexes',
            'dbHash',
            'dbStats',
            'dropCollection',
            'dropIndex',
            'dropSearchIndex',
            'find',
            'insert',
            'killCursors',
            'listCollections',
            'listIndexes',
            'listSearchIndexes',
            'updateSearchIndex',
            'planCacheRead',
            'performRawDataOperations',
            'remove',
            'renameCollectionSameDB',
            'update'
         ]
      },
      {
         resource: { db: 'test', collection: 'system.js' },
         actions: [
            'changeStream',
            'cleanupStructuredEncryptionData',
            'collStats',
            'compactStructuredEncryptionData',
            'convertToCapped',
            'createCollection',
            'createIndex',
            'createSearchIndexes',
            'dbHash',
            'dbStats',
            'dropCollection',
            'dropIndex',
            'dropSearchIndex',
            'find',
            'insert',
            'killCursors',
            'listCollections',
            'listIndexes',
            'listSearchIndexes',
            'updateSearchIndex',
            'planCacheRead',
            'performRawDataOperations',
            'remove',
            'renameCollectionSameDB',
            'update'
         ]
      }
   ],
   isBuiltin: true
}

Database User Roles

Every database includes the following client roles:

read

Provides read access to all non-system collections and the system.js collection.

Note

This role does not provide privileges to directly access the system.namespaces collection.

The role provides read access by granting the following actions:

Users without the listDatabases privilege action can run the listDatabases command to return a list of databases for which they have privileges. This includes databases where the user has privileges on specific collections. Run the command with the authorizedDatabases option unspecified or set to true.

readWrite

Provides all privileges of the read role plus the ability to modify data on all non-system collections and the system.js collection.

The role provides the following actions on those collections:

Database Administration Roles

Every database includes the following database administration roles:

dbAdmin

Provides the ability to perform administrative tasks such as schema-related tasks, indexing, and gathering statistics. This role does not grant privileges for user and role management.

The role provides the following privileges:

Resource

Permitted Actions

system.profile

All non-system collections: (database resource)

For these collections, dbAdmin does not include full read access such as find.

dbOwner: The database owner can perform any administrative action on the database. This role combines the privileges granted by the readWrite, dbAdmin and userAdmin roles.

userAdmin

Provides the ability to create and modify roles and users on the current database. The userAdmin role allows users to grant any privilege to any user, including themselves. This role also indirectly provides superuser access to either the database or, if scoped to the admin database, the cluster.

The userAdmin role explicitly provides the following actions:

Warning

Understand the security implications of granting the userAdmin role. A user with this role for a database can assign themselves any privilege on that database. Granting the userAdmin role on the admin database has further security implications as this indirectly provides superuser access to a cluster. With admin scope, a user with the userAdmin role can grant cluster-wide roles or privileges including userAdminAnyDatabase.

Cluster Administration Roles

The admin database includes the following roles for administering the whole system rather than just a single database. These roles include but are not limited to replica set and sharded cluster administrative functions.

clusterAdmin

Provides the greatest cluster-management access. This role combines the privileges granted by the clusterManager, clusterMonitor, and hostManager roles. The role also provides these additional permissions:

dropDatabase action
setQuerySettings and removeQuerySettings database commands
$querySettings aggregation stage

clusterManager

Provides management and monitoring actions on the cluster. Users with this role can access the config and local databases, which are used in sharding and replication, respectively. Additionally, the role provides the querySettings action.

Resource

Actions

cluster

All databases

clusterManager provides additional privileges for the config and local databases.

On the config database, permits the following actions:

Resource

Actions

All non-system collections in the config database

system.js

On the local database, permits the following actions:

Resource

Actions

All non-system collections in the local database

system.replset collection

clusterMonitor

Provides read-only access to monitoring tools, such as the MongoDB Cloud Manager and Ops Manager monitoring agent.

Permits the following actions on the cluster as a whole:

Permits the following actions on all databases in the cluster:

Permits the find action on all system.profile collections in the cluster.

On the config database, permits the following actions:

Resource	Actions
All non-system collections in the `config` database	`collStats` `dbHash` `dbStats` `find` `indexStats` `killCursors` `listCollections` `listIndexes` `listSearchIndexes` `planCacheRead`
`system.js` collection	`collStats` `dbHash` `dbStats` `find` `killCursors` `listCollections` `listIndexes` `planCacheRead`

On the local database, permits the following actions:

Resource	Actions
All non-system collections in the `local` database	`collStats` `dbHash` `dbStats` `find` `indexStats` `killCursors` `listCollections` `listIndexes` `listSearchIndexes` `planCacheRead`
`system.js` collection	`collStats` `dbHash` `dbStats` `find` `killCursors` `listCollections` `listIndexes` `listSearchIndexes` `planCacheRead`
`system.replset`, `system.profile`,	`find`

directShardOperations: Starting in MongoDB 8.0, you can use the directShardOperations role to perform maintenance operations that require you to execute commands directly against a shard.
Warning
Running commands using the directShardOperations role can cause your cluster to stop working correctly and may cause data corruption. Only use the directShardOperations role for maintenance purposes or under the guidance of MongoDB support. Stop using the directShardOperations role when you finish performing maintenance operations.

enableSharding

Provides the ability to enable sharding for a collection and modify existing shard keys.

Provides the following actions on all non-system collections:

analyzeShardKey
enableSharding
moveCollection (MongoDB 8.0 and later)
refineCollectionShardKey
reshardCollection
rewriteCollection (MongoDB 8.3 and later)
unshardCollection (MongoDB 8.0 and later)

hostManager

Provides the ability to monitor and manage servers.

On the cluster as a whole, provides the following actions:

On all databases in the cluster, provides the following actions:

killCursors

searchCoordinator

Provides readAnyDatabase privileges and write permissions on the __mdb_internal_search database.

Important

Do not modify the contents of the __mdb_internal_search database.

On the cluster as a whole, provides the following action:

bypassDefaultMaxTimeMS

Backup and Restoration Roles

The admin database includes the following roles for backing up and restoring data:

backup

Provides minimal privileges needed for backing up data. This role provides sufficient privileges to use the MongoDB Cloud Manager backup agent, Ops Manager backup agent, or to use mongodump to back up an entire mongod instance.

Provides the insert and update actions on the settings collection in the config database.

On anyResource, provides the following actions:

On the cluster as a whole, provides the following actions:

appendOplogNote
getParameter
listDatabases
serverStatus
setUserWriteBlockMode (Starting in MongoDB 6.0)

Provides the find action on the following:

All non-system collections in the cluster, including those in the config and local databases
The following system collections in the cluster: system.js and system.profile
The admin.system.users and admin.system.roles collections
The config.settings collection
Legacy system.users collections from versions of MongoDB prior to 2.6

Provides the insert and update actions on the config.settings collection.

The backup role provides additional privileges to back up the system.profile collection that exists when running with database profiling.

restore

Provides convertToCapped on non-system collections.

Provides the necessary privileges to restore data from backups if the data does not include system.profile collection data and you run mongorestore without the --oplogReplay option.

You need additional privileges if the backup data includes system.profile collection data or you run with --oplogReplay:

system.profile

If the backup data includes system.profile collection data and the target database does not contain the system.profile collection, mongorestore attempts to create the collection even though the program does not actually restore system.profile documents. The user requires additional privileges to perform createCollection and convertToCapped actions on the system.profile collection for a database.

Both the built-in roles dbAdmin and dbAdminAnyDatabase provide the additional privileges.

--oplogReplay

To run with --oplogReplay, create a user-defined role that has anyAction on anyResource.

Grant only to users who must run mongorestore with --oplogReplay.

Provides the following action on the cluster as a whole:

getParameter

Provides the following actions on all non-system collections:

Provides the following actions on system.js collection:

Provides the following action on anyResource:

listCollections

Provides the following actions on all non-system collections on the config and the local databases:

Provides the following actions on admin.system.version

Provides the following action on admin.system.roles

createIndex

Provides the following actions on admin.system.users and legacy system.users collections:

restore includes the ability to modify the documents in the admin.system.users collection using normal modification operations. However, only modify these data using the user management methods.

Provides the following action on the <database>.system.views collection:

dropCollection (Starting in MongoDB 6.0)

On the cluster as a whole, provides the following actions:

bypassWriteBlockingMode (Staring in MongoDB 6.0)
setUserWriteBlockMode (Starting in MongoDB 6.0)

All-Database Roles

The following roles are available on the admin database and provide privileges that apply to all databases except local and config:

readAnyDatabase

Provides the same read-only privileges as read on all databases except local and config. The role also provides the listDatabases action on the cluster as a whole.

This role grants permissions on database resources, not cluster administrative resources.

See also the clusterManager and clusterMonitor roles for access to the config and local databases.

readWriteAnyDatabase

Provides the same privileges as readWrite on all databases except local and config. The role also provides:

the listDatabases action on the cluster as a whole
the compactStructuredEncryptionData action

This role grants permissions on database resources, not cluster administrative resources.

See also the clusterManager and clusterMonitor roles for access to the config and local databases.

userAdminAnyDatabase

Provides the same access to user administration operations as userAdmin on all databases except local and config.

userAdminAnyDatabase also provides the following privilege actions on the cluster:

The role provides the following privilege actions on the system.users and system.roles collections on the admin database, and on legacy system.users collections from versions of MongoDB prior to 2.6:

The userAdminAnyDatabase role does not restrict the privileges that a user can grant. As a result, userAdminAnyDatabase users can grant themselves privileges in excess of their current privileges and even can grant themselves all privileges, even though the role does not explicitly authorize privileges beyond user administration. This role is effectively a MongoDB system superuser.

See also the clusterManager and clusterMonitor roles for access to the config and local databases.

dbAdminAnyDatabase

Provides the same privileges as dbAdmin on all databases except local and config. The role also provides the listDatabases action on the cluster as a whole.

See also the clusterManager and clusterMonitor roles for access to the config and local databases.

Starting in MongoDB 5.0, dbAdminAnyDatabase includes the applyOps privilege action.

Superuser Roles

Several roles provide either indirect or direct system-wide superuser access.

The following roles provide the ability to assign any user any privilege on any database. Users with one of these roles can assign themselves any privilege on any database:

dbOwner role, when scoped to the admin database
userAdmin role, when scoped to the admin database
userAdminAnyDatabase role

The following role provides full privileges on all resources:

root

Provides access to the operations and all the resources of the following combined roles:

readWriteAnyDatabase
dbAdminAnyDatabase
userAdminAnyDatabase
clusterAdmin
restore
backup

Also provides the following privilege actions:

validate on system. collections.
On MongoDB 8.0 and later, bypassDefaultMaxTimeMS, which causes all queries run by the user to ignore the value of defaultMaxTimeMS.

Changed in version 6.0:

The root role includes find and remove privileges on the system.preimages collection in the config database.

Internal Role

__system

MongoDB assigns this role to user objects that represent cluster members, such as replica set members and mongos instances. The role entitles its holder to take any action against any object in the database.

Do not assign this role to user objects representing applications or human administrators, other than in exceptional circumstances.

If you need access to all actions on all resources, for example to run applyOps commands, do not assign this role. Instead, create a user-defined role that grants anyAction on anyResource and ensure that only the users who need access to these operations have this access.

Learn More

If built-in roles do not meet your requirements, create user-defined roles. For more information, see User-Defined Roles on Self-Managed Deployments.

Back

Configure Database Users in Atlas

Custom Database Roles