diff --git a/source/core/access-control.txt b/source/core/access-control.txt index 99218eb0d1f..d9f9a911225 100644 --- a/source/core/access-control.txt +++ b/source/core/access-control.txt @@ -4,7 +4,7 @@ Access Control .. default-domain:: mongodb -MongoDB provides support for authentication and authorization on a +MongoDB provides support for authentication and :ref:`authorization` on a per-database level. Users exist in the context of a single logical database. @@ -24,7 +24,7 @@ a given :program:`mongod` or :program:`mongos` instance, use the :setting:`auth` and :setting:`keyFile` configuration settings. For details, see :doc:`/tutorial/enable-authentication`. -.. versionadded:: 2.6 +.. versionadded:: 2.5.4 MongoDB supports x.509 certificate authentication for use with a secure SSL connection. See :doc:`/tutorial/configure-x509`. @@ -47,103 +47,3 @@ using a Kerberos service is available. For Linux, see Each client connection should authenticate as exactly one user. - -.. _authorization: - -Authorization -------------- - -MongoDB uses a role-based approach to authorization. A user's access to -resources and operations depends on the user's roles. - -.. _roles: - -Roles -~~~~~ - -Roles contain the :ref:`privileges ` that allow users to perform -:doc:`actions ` on database :ref:`resources -`. A user assigned a role receives all the privileges of -that role. - -A role can consist of both privileges and other roles. A role :ref:`inherits -` the privileges of any contained roles. - -MongoDB provides both :doc:`built-in roles -` and the ability to create new -:ref:`user-defined roles `. - -.. _privileges: - -Privileges -`````````` - -A privilege is a set of permitted :doc:`actions -` on a defined :ref:`resource -`. - -For example, a privilege might permit the ``update`` action on the ``products`` -database, allowing a user to change data in *existing* documents on that -database. To instead create a *new* document on the ``products`` database -the user would need a privilege that permits the ``insert`` action on the -database. - -.. include:: /includes/fact-roles-privileges.rst - -.. _inheritance: - -Inheritance -``````````` - -A role can include one or more existing roles in its definition, in which case -the role inherits the privileges of the included roles. The role inherits -*all* the privileges of an included role. - -.. include:: /includes/fact-roles-inheritance.rst - -.. _user-defined-roles: - -User-Defined Roles -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2.6 - -MongoDB provides the ability to create -and manage custom roles. To create a role is to define its privileges -by pairing :ref:`resources ` (e.g. database, -collection) with :doc:`actions ` (e.g. -``insert``, ``find``), and/or by specifying other roles from which the -role inherits privileges. - -To create and manage roles, MongoDB provides :ref:`role management -commands `. MongoDB scopes each role to the -database in which it is created and uniquely identifies each role by -the pairing of its name and its database. MongoDB stores the -user-defined roles information in the :doc:`system.roles collection -` of the ``admin`` database. - -User-defined roles provide the ability to specify privileges at the -collection level. To configure collection-level access, create -privileges that pair actions to a particular collection. - -Role Assignment to Users -~~~~~~~~~~~~~~~~~~~~~~~~ - -Users can have multiple roles and can have different roles on different -databases. Assigning roles to a user authorizes the user to have only -the privileges granted by the roles. Roles always grant privileges and -never limit access. For example, if a user has both :authrole:`read` -*and* :authrole:`readWriteAnyDatabase` roles on a database, the greater -access prevails. A user's role assignments can include -:ref:`built-in roles ` provided by MongoDB or -a :ref:`custom roles ` defined by the user. - -To assign roles to users, you must be a user with an administrative -role in the database. As such, you must first create an administrative -user. For details, see :doc:`/tutorial/add-user-administrator` and -:doc:`/tutorial/add-user-to-database`. - -MongoDB stores each user's role assignments in the ``admin`` database's -:doc:`system.users collection `. To -manage data in this collection, MongoDB provides :ref:`user management -commands `. diff --git a/source/core/authorization.txt b/source/core/authorization.txt new file mode 100644 index 00000000000..cf2f9f37a48 --- /dev/null +++ b/source/core/authorization.txt @@ -0,0 +1,133 @@ +.. _authorization: + +============= +Authorization +============= + +.. default-domain:: mongodb + +MongoDB employs Role-Based Access Control (RBAC) to govern access to a +MongoDB system. A user is granted one or more :ref:`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 provides :doc:`built-in roles `, each +with a dedicated purpose for a common use case. Examples include the +:authrole:`read`, :authrole:`readWrite`, :authrole:`dbAdmin`, and +:authrole:`root` roles. + +Administrators also can create new roles and privileges to cater to +operational needs. Administrator 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: + +Roles +----- + +A role consists of privileges that pair resources with allowed operations. +Each privilege is defined directly in the role or inherited from another +role. + +A role's privileges apply to the database where the role is created. A role +created on the ``admin`` database can include privileges that apply to all +databases or to the :ref:`cluster `. + +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 :authrole:`read` *and* :authrole:`readWriteAnyDatabase` roles on a +database, the greater access prevails. + +.. _privileges: + +Privileges +~~~~~~~~~~ + +A privilege consists of a specified resource and the actions permitted on the +resource. + +A privilege :doc:`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 :doc:`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 +:doc:`/reference/privilege-actions`. + +For example, a privilege that includes the :authaction:`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 :authaction:`insert` action to +the privilege. + +For privilege syntax, see :data:`admin.system.roles.privileges`. + +.. _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. + +.. _user-defined-roles: + +User-Defined Roles +~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.5.4 + +User administrators can create custom roles to ensure collection-level and +command-level granularity and to adhere to the policy of :term:`least +privilege`. Administrators create and edit roles using the :ref:`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 :doc:`system.roles +` collection. Do not access this +collection directly but instead use the :ref:`role management commands +` to view and edit custom roles. + +Role Assignment to Users +------------------------ + +User administrators create the users that access the system's databases. +MongoDB's :ref:`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 :doc:`system.users collection +`. Do not access this collection directly +but instead use the :ref:`user management commands +`. + +The first role assigned in a database should be either :authrole:`userAdmin` +or :authrole:`userAdminAnyDatabase`. This user can then create all other users +in the system. See :doc:`/tutorial/add-user-administrator`. + +See Also +-------- + +:doc:`/reference/built-in-roles` + +:doc:`/reference/resource-document` + +:doc:`/reference/privilege-actions` + +:doc:`/tutorial/add-user-administrator` + +:doc:`/tutorial/add-user-to-database` diff --git a/source/includes/fact-roles-inheritance.rst b/source/includes/fact-roles-inheritance.rst deleted file mode 100644 index 76caf634f03..00000000000 --- a/source/includes/fact-roles-inheritance.rst +++ /dev/null @@ -1,3 +0,0 @@ -A user-defined role can inherit :ref:`privileges ` only from other -roles in its database, unless the role is scoped to the ``admin`` database. A -role scoped to the ``admin`` database can inherit from roles in any database. diff --git a/source/includes/fact-roles-privileges.rst b/source/includes/fact-roles-privileges.rst deleted file mode 100644 index 254633fa8ec..00000000000 --- a/source/includes/fact-roles-privileges.rst +++ /dev/null @@ -1,4 +0,0 @@ -A user-defined role grants :ref:`privileges ` only to the database -to which it is scoped, unless the role is scoped to the ``admin`` database. A -role scoped to the ``admin`` database can grant privileges on all databases, -as well as on the :ref:`cluster resource `. diff --git a/source/includes/toc-security-core-landing.yaml b/source/includes/toc-security-core-landing.yaml index 56f80028a25..6fc446691ae 100644 --- a/source/includes/toc-security-core-landing.yaml +++ b/source/includes/toc-security-core-landing.yaml @@ -1,6 +1,10 @@ file: /core/access-control description: | - Control access to MongoDB instances using authentication and authorization. + Control access to MongoDB instances using authentication. +--- +file: /core/authorization +description: | + Control access to MongoDB instances using authorization. --- file: /core/inter-process-authentication description: | diff --git a/source/includes/toc-spec-security-landing.yaml b/source/includes/toc-spec-security-landing.yaml index db42f431e82..469dbce4189 100644 --- a/source/includes/toc-spec-security-landing.yaml +++ b/source/includes/toc-spec-security-landing.yaml @@ -9,6 +9,8 @@ files: level: 1 - file: /core/access-control level: 2 + - file: /core/authorization + level: 2 - file: /core/security-network level: 2 - file: /core/security-interface diff --git a/source/reference/command/createRole.txt b/source/reference/command/createRole.txt index ec1666a8975..abd0e1eab8c 100644 --- a/source/reference/command/createRole.txt +++ b/source/reference/command/createRole.txt @@ -41,9 +41,11 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-privileges.rst - -.. include:: /includes/fact-roles-inheritance.rst +A role's privileges apply to the database where the role is created. The +role can inherit privileges from other roles in its database. A role +created on the ``admin`` database can include privileges that apply to all +databases or to the :ref:`cluster ` and can inherit +privileges from roles in other databases. Required Access --------------- diff --git a/source/reference/command/grantPrivilegesToRole.txt b/source/reference/command/grantPrivilegesToRole.txt index 255cb4b60a0..de492bed845 100644 --- a/source/reference/command/grantPrivilegesToRole.txt +++ b/source/reference/command/grantPrivilegesToRole.txt @@ -35,7 +35,9 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-privileges.rst +A role's privileges apply to the database where the role is created. A +role created on the ``admin`` database can include privileges that apply +to all databases or to the :ref:`cluster `. Required Access --------------- diff --git a/source/reference/command/grantRolesToRole.txt b/source/reference/command/grantRolesToRole.txt index 20c98a7db6d..993c035d211 100644 --- a/source/reference/command/grantRolesToRole.txt +++ b/source/reference/command/grantRolesToRole.txt @@ -35,7 +35,9 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-inheritance.rst +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. Required Access --------------- diff --git a/source/reference/command/updateRole.txt b/source/reference/command/updateRole.txt index 077bbf24c5c..15068afcce2 100644 --- a/source/reference/command/updateRole.txt +++ b/source/reference/command/updateRole.txt @@ -57,9 +57,11 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-privileges.rst - -.. include:: /includes/fact-roles-inheritance.rst +A role's privileges apply to the database where the role is created. The +role can inherit privileges from other roles in its database. A role +created on the ``admin`` database can include privileges that apply to all +databases or to the :ref:`cluster ` and can inherit +privileges from roles in other databases. Required Access --------------- diff --git a/source/reference/method/db.createRole.txt b/source/reference/method/db.createRole.txt index b4415b3bdf7..cd35f0b10d4 100644 --- a/source/reference/method/db.createRole.txt +++ b/source/reference/method/db.createRole.txt @@ -47,9 +47,11 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-privileges.rst - -.. include:: /includes/fact-roles-inheritance.rst +A role's privileges apply to the database where the role is created. The +role can inherit privileges from other roles in its database. A role +created on the ``admin`` database can include privileges that apply to all +databases or to the :ref:`cluster ` and can inherit +privileges from roles in other databases. Required Access --------------- diff --git a/source/reference/method/db.grantPrivilegesToRole.txt b/source/reference/method/db.grantPrivilegesToRole.txt index 37555095e8f..bf9f17f3d55 100644 --- a/source/reference/method/db.grantPrivilegesToRole.txt +++ b/source/reference/method/db.grantPrivilegesToRole.txt @@ -44,7 +44,9 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-privileges.rst +A role's privileges apply to the database where the role is created. A +role created on the ``admin`` database can include privileges that apply +to all databases or to the :ref:`cluster `. Required Access --------------- diff --git a/source/reference/method/db.grantRolesToRole.txt b/source/reference/method/db.grantRolesToRole.txt index 4db2436a714..ac3624fdf42 100644 --- a/source/reference/method/db.grantRolesToRole.txt +++ b/source/reference/method/db.grantRolesToRole.txt @@ -30,7 +30,9 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-inheritance.rst +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. Required Access --------------- diff --git a/source/reference/method/db.updateRole.txt b/source/reference/method/db.updateRole.txt index 4825cdf9013..accda72603a 100644 --- a/source/reference/method/db.updateRole.txt +++ b/source/reference/method/db.updateRole.txt @@ -67,9 +67,11 @@ Definition Behavior -------- -.. include:: /includes/fact-roles-privileges.rst - -.. include:: /includes/fact-roles-inheritance.rst +A role's privileges apply to the database where the role is created. The +role can inherit privileges from other roles in its database. A role +created on the ``admin`` database can include privileges that apply to all +databases or to the :ref:`cluster ` and can inherit +privileges from roles in other databases. Required Access --------------- diff --git a/source/reference/system-roles-collection.txt b/source/reference/system-roles-collection.txt index 137f39fae3c..c97c75a8bc8 100644 --- a/source/reference/system-roles-collection.txt +++ b/source/reference/system-roles-collection.txt @@ -98,12 +98,6 @@ A ``system.roles`` document has the following fields: The :data:`~admin.system.roles.roles` array contains role documents that specify the roles from which this role :ref:`inherits ` privileges. - .. include:: /includes/fact-roles-inheritance.rst - - .. COMMENT not sure we need the above inclusion since this collection - shows the effects of the create/update and has no bearing on what - is allowed. - A role document has the following syntax: .. code-block:: javascript diff --git a/source/tutorial/define-roles.txt b/source/tutorial/define-roles.txt index 041381f0d0d..09507ddd6dc 100644 --- a/source/tutorial/define-roles.txt +++ b/source/tutorial/define-roles.txt @@ -15,16 +15,14 @@ access to a MongoDB system. However, if these roles cannot describe the desired privilege set of a particular user type in a deployment, you can define a new, customized role. -MongoDB limits the scope of each role to the database where the role -was created. The combination of the database name and the role name -uniquely defines a role in MongoDB. - -Considerations --------------- +A role's privileges apply to the database where the role is created. The +role can inherit privileges from other roles in its database. A role +created on the ``admin`` database can include privileges that apply to all +databases or to the :ref:`cluster ` and can inherit +privileges from roles in other databases. -.. include:: /includes/fact-roles-privileges.rst - -.. include:: /includes/fact-roles-inheritance.rst +The combination of the database name and the role name +uniquely defines a role in MongoDB. .. _define-roles-prereq: