- Security >
- Security Concepts >
- Authorization
Authorization¶
On this page
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.