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

Authorization

MongoDB employs Role-Based Access Control (RBAC) to govern access to a MongoDB system. A user is granted one or more roles that determine the user’s access to database resources and operations. Outside of role assignments, the user has no access to the system.

MongoDB does not enable authorization by default. You can enable authorization using the --auth or the --keyFile options, or if using a configuration file, with the security.authorization or the security.keyFile settings.

MongoDB provides built-in roles, each with a dedicated purpose for a common use case. Examples include the read, readWrite, dbAdmin, and root roles.

Administrators also can create new roles and privileges to cater to operational needs. Administrators can assign privileges scoped as granularly as the collection level.

When granted a role, a user receives all the privileges of that role. A user can have several roles concurrently, in which case the user receives the union of all the privileges of the respective roles.

Roles

A role consists of privileges that pair resources with allowed operations. Each privilege is specified explicitly in the role or inherited from another role or both.

Except for roles created in the admin database, a role can only include privileges that apply to its database and can only inherit from other roles in its database.

A role created in the admin database can include privileges that apply to the admin database, other databases or to the cluster resource, and can inherit from roles in other databases as well as the admin database.

A user assigned a role receives all the privileges of that role. The user can have multiple roles and can have different roles on different databases.

Roles always grant privileges and never limit access. For example, if a user has both read and readWriteAnyDatabase roles on a database, the greater access prevails.

Privileges

A privilege consists of a specified resource and the actions permitted on the resource.

A privilege resource is either a database, collection, set of collections, or the cluster. If the cluster, the affiliated actions affect the state of the system rather than a specific database or collection.

An action is a command or method the user is allowed to perform on the resource. A resource can have multiple allowed actions. For available actions see Privilege Actions.

For example, a privilege that includes the update action allows a user to modify existing documents on the resource. To additionally grant the user permission to create documents on the resource, the administrator would add the insert action to the privilege.

For privilege syntax, see admin.system.roles.privileges.

Inherited Privileges

A role can include one or more existing roles in its definition, in which case the role inherits all the privileges of the included roles.

A role can inherit privileges from other roles in its database. A role created on the admin database can inherit privileges from roles in any database.

User-Defined Roles

New in version 2.6.

User administrators can create custom roles to ensure collection-level and command-level granularity and to adhere to the policy of least privilege. Administrators create and edit roles using the role management commands.

MongoDB scopes a user-defined role to the database in which it is created and uniquely identifies the role by the pairing of its name and its database. MongoDB stores the roles in the admin database’s system.roles collection. Do not access this collection directly but instead use the role management commands to view and edit custom roles.

Collection-Level Access Control

By creating a role with privileges that are scoped to a specific collection in a particular database, administrators can implement collection-level access control.

See Collection-Level Access Control for more information.

Users

MongoDB stores user credentials in the protected admin.system.users. Use the user management methods to view and edit user credentials.

Role Assignment to Users

User administrators create the users that access the system’s databases. MongoDB’s user management commands let administrators create users and assign them roles.

MongoDB scopes a user to the database in which the user is created. MongoDB stores all user definitions in the admin database, no matter which database the user is scoped to. MongoDB stores users in the admin database’s system.users collection. Do not access this collection directly but instead use the user management commands.

The first role assigned in a database should be either userAdmin or userAdminAnyDatabase. This user can then create all other users in the system. See Create a User Administrator.

Protect the User and Role Collections

MongoDB stores role and user data in the protected admin.system.roles and admin.system.users collections, which are only accessible using the user management methods.

If you disable access control, do not modify the admin.system.roles and admin.system.users collections using normal insert() and update() operations.

Additional Information

See the reference section for documentation of all built-in-roles and all available privilege actions. Also consider the reference for the form of the resource documents.

To create users see the Create a User Administrator and Add a User to a Database tutorials.