Navigation
This version of the documentation is archived and no longer supported.

User Privilege Roles in MongoDB

On this page

New in version 2.4: In version 2.4, MongoDB adds support for the following user roles:

Roles

Changed in version 2.4.

Roles in MongoDB provide users with a set of specific privileges, on specific logical databases. Users may have multiple roles and may have different roles on different logical database. Roles only grant privileges and never limit access: if a user has read and readWriteAnyDatabase permissions on the records database, that user will be able to write data to the records database.

Note

By default, MongoDB 2.4 is backwards-compatible with the MongoDB 2.2 access control roles. You can explicitly disable this backwards-compatibility by setting the supportCompatibilityFormPrivilegeDocuments option to 0 during startup, as in the following command-line invocation of MongoDB:

copy 
mongod --setParameter supportCompatibilityFormPrivilegeDocuments=0

In general, you should set this option if your deployment does not need to support legacy user documents. Typically legacy user documents are only useful during the upgrade process and while you migrate applications to the updated privilege document form.

See privilege documents and Delegated Credentials for MongoDB Authentication for more information about permissions and authentication in MongoDB.

Database User Roles

read

Provides users with the ability to read data from any collection within a specific logical database. This includes find() and the following database commands:

readWrite

Provides users with the ability to read from or write to any collection within a specific logical database. Users with readWrite have access to all of the operations available to read users, as well as the following basic write operations: insert(), remove(), and update().

Additionally, users with the readWrite have access to the following database commands:

Database Administration Roles

dbAdmin

Provides the ability to perform the following set of administrative operations within the scope of this logical database.

Furthermore, only dbAdmin has the ability to read the system.profile collection.

userAdmin

Allows users to read and write data to the system.users collection of the user’s database. Users with this role will be able to modify permissions for existing users and create new users. userAdmin does not restrict the permissions that a user can grant, and a userAdmin user can grant privileges to themselves or other users in excess of the userAdmin users’ current privileges.

Important

userAdmin is effectively the superuser role for a specific database. Users with userAdmin can grant themselves all privileges. However, userAdmin does not explicitly authorize a user for any privileges beyond user administration.

Note

The userAdmin role is a database-specific privilege, and only grants a user the ability to administer users on a single database. However, for the admin database, userAdmin allows a user the ability to gain userAdminAnyDatabase. Thus, for the admin database only, these roles are effectively the same.

Administrative Roles

clusterAdmin

clusterAdmin grants access to several administration operations that affect or present information about the whole system, rather than just a single database. These privileges include but are not limited to replica set and sharded cluster administrative functions.

clusterAdmin is only applicable on the admin database, and does not confer any access to the local or config databases.

Specifically, users with the clusterAdmin role have access to the following operations:

For some cluster administration operations, MongoDB requires read and write access to the local or config databases. You must specify this access separately from clusterAdmin. See the Combined Access section for more information.

Any Database Roles

Note

You must specify the following “any” database roles on the admin databases. These roles apply to all databases in a mongod instance and are roughly equivalent to their single-database equivalents.

If you add any of these roles to a user privilege document outside of the admin database, the privilege will have no effect. However, only the specification of the roles must occur in the admin database, with delegated authentication credentials, users can gain these privileges by authenticating to another database.

readAnyDatabase

readAnyDatabase provides users with the same read-only permissions as read, except it applies to all logical databases in the MongoDB environment.

readWriteAnyDatabase

readWriteAnyDatabase provides users with the same read and write permissions as readWrite, except it applies to all logical databases in the MongoDB environment.

userAdminAnyDatabase

userAdminAnyDatabase provides users with the same access to user administration operations as userAdmin, except it applies to all logical databases in the MongoDB environment.

Important

Because users with userAdminAnyDatabase and userAdmin have the ability to create and modify permissions in addition to their own level of access, this role is effectively the MongoDB system superuser. However, userAdminAnyDatabase and userAdmin do not explicitly authorize a user for any privileges beyond user administration.

dbAdminAnyDatabase

dbAdminAnyDatabase provides users with the same access to database administration operations as dbAdmin, except it applies to all logical databases in the MongoDB environment.

Combined Access

Some operations are only available to users that have multiple roles. Consider the following:

sh.status()
Requires clusterAdmin and read access to the config database.
applyOps, eval [1]
Requires readWriteAnyDatabase, userAdminAnyDatabase, dbAdminAnyDatabase and clusterAdmin (on the admin database.)

Some operations related to cluster administration are not available to users who only have the clusterAdmin role:

rs.conf()
Requires read on the local database.
sh.addShard()
Requires readWrite on the config database.
[1]The mongo shell provides db.eval() as a helper for the eval command. As a wrapper, db.eval() requires the same privileges.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.