authorization.txt

.. _authorization:

=========================
Role-Based Access Control
=========================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

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

Enable Access Control
---------------------

MongoDB does not enable access control by default. You can enable
authorization using the :option:`--auth <mongod --auth>` or the
:setting:`security.authorization` setting. Enabling :doc:`internal
authentication </core/security-internal-authentication>` also enables
client authorization.

Once access control is enabled, users must :doc:`authenticate
</core/authentication>` themselves.

.. _roles:

Roles
-----

A role grants privileges to perform the specified :ref:`actions
<security-user-actions>` on :doc:`resource
</reference/resource-document>`. Each privilege is either specified
explicitly in the role or inherited from another role or both.

.. _privileges:

Privileges
~~~~~~~~~~

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

A :doc:`resource </reference/resource-document>` is a database,
collection, set of collections, or the cluster. If the resource is the
cluster, the affiliated actions affect the state of the system rather
than a specific database or collection. For information on the resource
documents, see :doc:`/reference/resource-document`.

An :doc:`action </reference/privilege-actions>` specifies the operation
allowed on the resource. For available actions see
:doc:`/reference/privilege-actions`.

.. _inheritance:

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.

View Role's Privileges
~~~~~~~~~~~~~~~~~~~~~~

You can view the privileges for a role by issuing the :dbcommand:`rolesInfo`
command with the ``showPrivileges`` and ``showBuiltinRoles`` fields both set to
``true``.

Users and Roles
---------------

You can assign roles to users during the user creation. You can also
update existing users to grant or revoke roles. For a full list of user
management methods, see :ref:`user-management-methods`

A user assigned a role receives all the privileges of that role. A user
can have multiple roles. By assigning to the user roles in various
databases, a user created in one database can have permissions to act on
other databases.

.. note::

   The first user created in the database should be a user administrator
   who has the privileges to manage other users. See
   :doc:`/tutorial/enable-authentication`.

Built-In Roles and User-Defined Roles
-------------------------------------

MongoDB provides :doc:`built-in roles </reference/built-in-roles>` that
provide set of privileges commonly needed in a database system.

If these built-in-roles cannot provide the desired set of privileges,
MongoDB provides methods to create and modify :doc:`user-defined roles
</core/security-user-defined-roles>`.

LDAP Authorization
------------------

MongoDB Enterprise supports querying an LDAP server for the LDAP groups the
authenticated user is a member of. MongoDB maps the Distinguished Names (DN)
of each returned group to :ref:`roles <roles>` on the ``admin`` database.
MongoDB authorizes the user based on the mapped roles and their associated
privileges. See :ref:`LDAP Authorization <security-ldap-external>` for more
information.

.. toctree::
   :titlesonly:
   :hidden:

   /reference/built-in-roles
   /core/security-user-defined-roles
   /tutorial/manage-users-and-roles
   /tutorial/change-own-password-and-custom-data
   /core/collection-level-access-control
   /core/security-ldap-external