DOCS-2311 create a custom role

source/core/access-control.txt

@@ -53,11 +53,53 @@ using a Kerberos service is available. For Linux, see
 Authorization
 -------------
 
-MongoDB provisions authorization, or access to databases and
-operations, on a per-database level. MongoDB uses a role-based approach
-to authorization. A role grants privileges to users, where
-privileges specify the :doc:`actions </reference/privilege-actions>`
-permitted on various :ref:`resources <resource-document>`.
+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:`system-defined roles
+</reference/system-defined-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:
 
@@ -66,41 +108,23 @@ User-Defined Roles
 
 .. versionadded:: 2.6
 
-In addition to the MongoDB :doc:`system-defined roles
-</reference/system-defined-roles>`, MongoDB provides the ability to create
+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.
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
-
 To create and manage roles, MongoDB provides :ref:`role management
-commands <role-management-commands>`. MongoDB scopes each role to the
+commands <role-management-commands>`. MongoDB scopes each role in 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.
 
-.. seealso:: :dbcommand:`createRole` and :ref:`role-management-commands`.
-
-.. _collection-level-access-control:
-
-Collection-Level Access Control
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 2.6
-
-MongoDB provides the ability to specify user privileges at a
-collection-level granularity. To specify collection-level access
-control, create a custom role that pairs its actions to a particular
-collection in that database in the :ref:`resource document
-<resource-document>`.
-
-The MongoDB :doc:`system-defined roles </reference/system-defined-roles>`
-grant privileges at a database-level only, and thus cannot be used to
-control privileges at the collection-level.
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -122,5 +146,4 @@ user. For details, see :doc:`/tutorial/add-user-administrator` and
 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>`, which require proper
-authorization to use in order to prevent privilege escalation attacks.
+commands <user-management-commands>`.

source/includes/fact-roles-inheritance.rst

@@ -0,0 +1,3 @@
+A user-defined role can inherit :ref:`privileges <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.

source/includes/fact-roles-privileges.rst

@@ -0,0 +1,4 @@
+A user-defined role grants :ref:`privileges <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 <resource-cluster>`.

source/includes/steps-define-roles.yaml

@@ -0,0 +1,75 @@
+source:
+  file: steps-change-user-privileges.yaml
+  ref: connect-with-appropriate-privileges
+pre: |
+  Connect to the :program:`mongod` or :program:`mongos` with the privileges
+  required in the :ref:`define-roles-prereq` section.
+---
+source:
+  file: steps-change-user-privileges.yaml
+  ref: verify-privileges
+---
+title: Define the Privileges to Grant to the Role
+stepnum: 3
+ref: define-privileges
+pre: |
+  Decide which :ref:`resources <resource-document>` to grant access to and
+  which :ref:`actions <security-user-actions>` to grant on each resource.
+action:
+  pre: |
+    When creating the role, you will enter the resource-action pairings as
+    documents in the ``privileges`` array, as in the following example:
+  language: javascript
+  code: |
+    { db: "products", collection: "electronics" }
+---
+title: Check whether an Existing Role Provides the Privileges
+stepnum: 4
+ref: check-existing-roles
+pre: |
+  If an existing role contains the exact set of :ref:`privileges
+  <privileges>`, the new role can :ref:`inherit <inheritance>` those
+  privileges.
+action:
+  pre: |
+    To view the privileges provided by existing roles, use the
+    :dbcommand:`rolesInfo` command, as in the following:
+  language: javascript
+  code: |
+    db.runCommand( { rolesInfo: 1, showPrivileges: 1 } )
+---
+title: Create the Role
+stepnum: 55
+ref: create-role
+pre: |
+  To create the role, use the :dbcommand:`createRole` command. Specify privileges
+  in the ``privileges`` array and inherited roles in the ``roles`` array.
+action:
+  pre: |
+    The following example creates the ``myClusterwideAdmin`` role in the
+    ``admin`` database:
+  language: javascript
+  code: |
+    use admin
+    db.createRole(
+      {
+        role: "myClusterwideAdmin",
+        privileges:
+        [
+          { resource: { cluster: true }, actions: [ "addShard" ] },
+          { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert" ] },
+          { resource: { db: "users", collection: "usersCollection" }, actions: [ "update" ] },
+          { resource: { db: "", collection: "" }, actions: [ "find" ] }
+        ],
+        roles:
+        [
+          { role: "read", db: "admin" }
+        ],
+        writeConcern: { w: "majority" , wtimeout: 5000 }
+      }
+    )
+  post: |
+    The operation defines ``myClusterwideAdmin`` role's privileges in the
+    ``privileges`` array. In the ``roles`` array, ``myClusterwideAdmin``
+    inherits privileges from the ``admin`` database's ``read`` role.
+...

source/reference/command/createRole.txt

@@ -9,7 +9,8 @@ Definition
 
 .. dbcommand:: createRole
 
-   Creates a role and specifies its privileges. The role applies to the
+   Creates a role and specifies its :ref:`privileges <privileges>`.
+   The role applies to the
    database on which you run the command. The :dbcommand:`createRole`
    command returns a *duplicate role* error if the role already exists in
    the database.
@@ -40,7 +41,9 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
+.. include:: /includes/fact-roles-privileges.rst
+
+.. include:: /includes/fact-roles-inheritance.rst
 
 Required Access
 ---------------

source/reference/command/grantPrivilegesToRole.txt

@@ -9,7 +9,7 @@ Definition
 
 .. dbcommand:: grantPrivilegesToRole
 
-   Assigns additional privileges to a :ref:`user-defined
+   Assigns additional :ref:`privileges <privileges>` to a :ref:`user-defined
    <user-defined-roles>` role defined on the database on which the
    command is run. The :dbcommand:`grantPrivilegesToRole` command uses
    the following syntax:
@@ -35,8 +35,7 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
-   :end-before: inherit-role
+.. include:: /includes/fact-roles-privileges.rst
 
 Required Access
 ---------------

source/reference/command/grantRolesToRole.txt

@@ -35,8 +35,7 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
-   :start-after: inherit-role
+.. include:: /includes/fact-roles-inheritance.rst
 
 Required Access
 ---------------
@@ -48,9 +47,9 @@ Example
 
 
 The following :dbcommand:`grantRolesToRole` command updates the
-``productsReaderWriter`` role in the ``products`` database to inherit
-the privileges of the ``productsReader`` role in the ``products``
-database:
+``productsReaderWriter`` role in the ``products`` database to :ref:`inherit
+<inheritance>` the :ref:`privileges <privileges>` of the ``productsReader``
+role in the ``products`` database:
 
 .. code-block:: javascript
 

source/reference/command/updateRole.txt

@@ -13,8 +13,8 @@ Definition
    :dbcommand:`updateRole` command must run on the role's database.
 
    An update to a field **completely replaces** the previous field's values.
-   To grant or remove roles or privileges without replacing all values, use
-   one or more of the following commands:
+   To grant or remove roles or :ref:`privileges <privileges>` without
+   replacing all values, use one or more of the following commands:
 
    - :dbcommand:`grantRolesToRole`
    - :dbcommand:`grantPrivilegesToRole`
@@ -57,7 +57,9 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
+.. include:: /includes/fact-roles-privileges.rst
+
+.. include:: /includes/fact-roles-inheritance.rst
 
 Required Access
 ---------------

source/reference/method/db.createRole.txt

@@ -9,7 +9,8 @@ Definition
 
 .. method:: db.createRole ( role, writeConcern )
 
-   Creates a role and specifies its privileges. The role applies to the
+   Creates a role and specifies its :ref:`privileges <privileges>`.
+   The role applies to the
    database on which you run the method. The :method:`db.createRole()`
    method returns a *duplicate role* error if the role already exists in the
    database.
@@ -46,7 +47,9 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
+.. include:: /includes/fact-roles-privileges.rst
+
+.. include:: /includes/fact-roles-inheritance.rst
 
 Required Access
 ---------------

source/reference/method/db.grantPrivilegesToRole.txt

@@ -9,7 +9,7 @@ Definition
 
 .. method:: db.grantPrivilegesToRole ( rolename, privileges, writeConcern )
 
-   Grants additional privileges to a :ref:`user-defined
+   Grants additional :ref:`privileges <privileges>` to a :ref:`user-defined
    <user-defined-roles>` role.
 
    The :method:`grantPrivilegesToRole()` method uses the following syntax:
@@ -44,8 +44,7 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
-   :end-before: inherit-role
+.. include:: /includes/fact-roles-privileges.rst
 
 Required Access
 ---------------

source/reference/method/db.grantRolesToRole.txt

@@ -30,8 +30,7 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
-   :start-after: inherit-role
+.. include:: /includes/fact-roles-inheritance.rst
 
 Required Access
 ---------------
@@ -44,14 +43,14 @@ Example
 .. TODO Update this example
 
 The following :method:`grantRolesToRole()` operation updates the
-``productsReaderWriter`` role in the ``products`` database to inherit
-the privileges of ``productsReader`` role also in the ``products``
-database:
+``productsReaderWriter`` role in the ``products`` database to :ref:`inherit
+<inheritance>` the :ref:`privileges <privileges>` of ``productsReader`` role:
 
 .. code-block:: javascript
 
    use products
-   db.grantRolesToRole( "productsReaderWriter",
-                        [ "productsReader" ],
-                        { w: "majority" , wtimeout: 5000 }
-                      )
+   db.grantRolesToRole(
+       "productsReaderWriter",
+       [ "productsReader" ],
+       { w: "majority" , wtimeout: 5000 }
+   )

source/reference/method/db.updateRole.txt

@@ -13,8 +13,8 @@ Definition
    :method:`db.updateRole()` method must run on the role's database.
 
    An update to a field **completely replaces** the previous field's values.
-   To grant or remove roles or privileges without replacing all values, use
-   one or more of the following methods:
+   To grant or remove roles or :ref:`privileges <privileges>` without
+   replacing all values, use one or more of the following methods:
 
    - :method:`db.grantRolesToRole()`
    - :method:`db.grantPrivilegesToRole()`
@@ -67,7 +67,9 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/privilege-resource-for-non-admin-roles.rst
+.. include:: /includes/fact-roles-privileges.rst
+
+.. include:: /includes/fact-roles-inheritance.rst
 
 Required Access
 ---------------