DOCS-2480 authorization 2.6 concepts doc

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 <privileges>` that allow users to perform
-:doc:`actions </reference/privilege-actions>` on database :ref:`resources
-<resource-document>`. 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
-<inheritance>` the privileges of any contained roles.
-
-MongoDB provides both :doc:`built-in roles
-</reference/built-in-roles>` and the ability to create new
-:ref:`user-defined roles <user-defined-roles>`.
-
-.. _privileges:
-
-Privileges
-``````````
-
-A privilege is a set of permitted :doc:`actions
-</reference/privilege-actions>` on a defined :ref:`resource
-<resource-document>`.
-
-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 <resource-document>` (e.g. database,
-collection) with :doc:`actions </reference/privilege-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 <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
-</reference/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 <built-in-roles>` provided by MongoDB or
-a :ref:`custom roles <user-defined-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 </reference/system-users-collection>`. To
-manage data in this collection, MongoDB provides :ref:`user management
-commands <user-management-commands>`.

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 <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 </reference/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 <resource-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 </reference/resource-document>` 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 </reference/privilege-actions>` 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 <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
+</reference/system-roles-collection>` collection. Do not access this
+collection directly but instead use the :ref:`role management commands
+<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 <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
+</reference/system-users-collection>`. Do not access this collection directly
+but instead use the :ref:`user management commands
+<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`

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: |

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

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 <resource-cluster>` and can inherit
+privileges from roles in other databases.
 
 Required Access
 ---------------

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 <resource-cluster>`.
 
 Required Access
 ---------------

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
 ---------------

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 <resource-cluster>` and can inherit
+privileges from roles in other databases.
 
 Required Access
 ---------------

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 <resource-cluster>` and can inherit
+privileges from roles in other databases.
 
 Required Access
 ---------------

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 <resource-cluster>`.
 
 Required Access
 ---------------

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
 ---------------

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 <resource-cluster>` and can inherit
+privileges from roles in other databases.
 
 Required Access
 ---------------