DOCS-2310 modify a user's access

source/includes/steps-change-user-privileges.yaml

@@ -1,124 +1,108 @@
-title: Identify User's Roles
+title: Connect with Access to Grant and Revoke Roles
 stepnum: 1
-ref: collect-roles
+ref: connect-with-grant-and-revoke-role-privileges
 pre: |
-  Use the :dbcommand:`usersInfo` command or :method:`db.getUser()` method to
-  display user information. The :data:`~admin.system.users.roles` array
-  specifies the user's roles.
+  Connect to the :program:`mongod` or :program:`mongos` with privileges that
+  include the :authaction:`grantRole` and :authaction:`revokeRole` actions on
+  the role's database. Connect as a user with those actions, or connect using
+  the :ref:`localhost exception <localhost-exception>`.
 action:
-  - pre: |
-      For example, to view roles for ``accountUser01`` on the
-      ``accounts`` database, issue the following:
-    code: |
-      use accounts
-      db.getUser("accountUser01")
-    language: javascript
-  - pre: |
-      The :data:`~admin.system.users.roles` array displays all roles
-      for ``accountUser01``:
-    language: javascript
-    code: |
-      "roles" : [
-         {
-           "role" : "readWrite",
-           "db" : "accounts"
-         },
-         {
-           "role" : "siteRole01",
-           "db" : "records"
-          }
-      ]
+  pre: |
+    The following example operation connects to MongoDB as an authenticated
+    user named ``roleManager``:
+  language: javascript
+  code: |
+    mongo --port 27017 -u roleManager -p 12345678 --authenticationDatabase admin
 ---
-title: Identify the Privileges Granted by the Roles
-ref: identify-privileges
+title: Verify Privileges
 stepnum: 2
+ref: verify-grant-and-revoke-role-privileges
 pre: |
-  For a given role, use the :dbcommand:`rolesInfo` command or
-  :method:`db.getRole()` method, and include the ``showPrivileges`` parameter.
-  The resulting role document displays the privileges granted directly and the
-  roles from which this role inherits privileges.
+  Once connected, check that you have the :authaction:`grantRole`
+  and :authaction:`revokeRole` actions on the appropriate database.
 action:
-  - pre: |
-      For example, to view the privileges granted by ``siteRole01``, use the
-      following operation:
-    language: javascript
-    code: |
-      use records
-      db.getRole( "siteRole01", { showPrivileges: true } )
-  - pre: |
-      In the :data:`~admin.system.roles.roles` array, ``siteRole01`` inherits
-      privileges from the ``corporate`` database's ``read`` role. In
-      :data:`~admin.system.roles.privileges` array, ``siteRole01``
-      grants the privilege to perform ``find``, ``insert``, and
-      ``update`` actions on the ``records`` database.
-    language: javascript
-    code: |
-         "roles" : [
-            {
-                "role" : "read",
-                "db" : "corporate"
-            }
-         ],
-         "privileges" : [
-            {
-                "resource" : {
-                    "db" : "records",
-                    "collection" : ""
-                },
-                "actions" : [
-                    "find",
-                    "insert",
-                    "update"
-                ]
-            }
-         ]
-post: |
-  To view the privileges granted by the :authrole:`read` role, use
-  :method:`db.getRole()` again with the appropriate parameters.
+  pre: |
+    The following example checks privileges for the user connected as
+    ``roleManager``:
+  language: javascript
+  code: |
+    db.runCommand(
+      {
+        usersInfo:"roleManager",
+        showPrivileges:true
+      }
+    )
+  post: |
+    The resulting ``users`` document displays the privileges granted to the user.
 ---
-title: Identify the Privileges to Grant or Revoke
+title: Identify the User's Roles and Privileges
 stepnum: 3
-ref: select-roles-to-modify
+ref: identify-privileges
 pre: |
-  Determine which role contains the privileges *and only those privileges*.
-
-  If such a role does not exist, then to grant the privileges will require
-  :doc:`creating a new role </tutorial/define-roles>` with the specific
-  set of privileges.
-
-  To revoke a subset of privileges provided by an existing role: revoke
-  the original role, :doc:`create a new role </tutorial/define-roles>`
-  that contains the privileges *to keep*, and then grant that role to
-  the user.
+  To display the roles and privileges of the user to be modified, use the
+  :method:`db.getUser()` and :method:`db.getRole()` methods, as described in
+  :doc:`/tutorial/verify-user-privileges`.
+action:
+  pre: |
+    For example, to view roles for ``accountUser01`` on the current database, issue:
+  code: |
+    db.getUser("accountUser01")
+  language: javascript
+action:
+  pre: |
+    To display the privileges granted by ``siteRole01`` on the current database, issue:
+  code: |
+    db.getRole( "siteRole01", { showPrivileges: true } )
+  language: javascript
 ---
-title: Modify User
+title: Identify the Privileges to Grant or Revoke
 stepnum: 4
+ref: select-roles-to-modify
+pre: |
+  Determine which role contains the privileges *and only those privileges*. If
+  such a role does not exist, then to grant the privileges will require
+  :doc:`creating a new role </tutorial/define-roles>` with the specific set of
+  privileges. To revoke a subset of privileges provided by an existing role:
+  revoke the original role, :doc:`create a new role </tutorial/define-roles>`
+  that contains the privileges *to keep*, and then grant that role to the
+  user.
+---
+title: Modify the User's Access
+stepnum: 5
 ref: user-modification
 action:
-  - heading:  Revoke a Role
+  - heading: Revoke a Role
     pre: |
-      Revoke a role with the :method:`db.revokeRolesFromUser()`
-      method. Use the following operation to remove the 
+      Revoke a role with the :method:`db.revokeRolesFromUser()` method. Access
+      revocations apply as soon as the user tries to run a command. On a
+      :program:`mongos` revocations are instant on the :program:`mongos` on
+      which the command ran, but there is up to a 10-delay before the user
+      cache is updated on the other :program:`mongos` instances in the
+      cluster. The following example operation removes the
       :authrole:`readWrite` role on the ``accounts`` database from the
       ``accountUser01`` user's existing roles:
     language: javascript
     code: |
       use accounts
       db.revokeRolesFromUser(
           "accountUser01",
-          [ { role: "readWrite", db: "accounts" } ]
+          [
+            { role: "readWrite", db: "accounts" }
+          ]
       )
   - heading: Grant a Role
     pre: |
       Grant a role using the :method:`db.grantRolesToUser()`
-      method. Use the following operation to grant the
+      method. For example, the following operation grants the
       ``accountUser01`` user the :authrole:`read` role on the
       ``records`` database:
     language: javascript
     code: |
       use accounts
       db.grantRolesToUser(
           "accountUser01",
-          [ { role: "read", db: "records" } ]
+          [
+            { role: "read", db: "records" }
+          ]
       )
 ...

source/tutorial/change-user-privileges.txt

@@ -1,22 +1,24 @@
 ======================
-Modify User Privileges
+Modify a User's Access
 ======================
 
 .. default-domain:: mongodb
 
 Overview
 --------
 
-A user's privileges determine the  :ref:`actions
-<security-user-actions>` available to that user in the context of a
-:ref:`resource <resource-document>`. Users receive privileges
-through role assignments. A user can have multiple roles, and each role
-can have multiple privileges.
+When a user's responsibilities change, modify the user's access to include
+only those roles the user requires. This follows the policy of :term:`least
+privilege`.
 
-Grant and revoke the user's roles using the :dbcommand:`grantRolesToUser`
-and :dbcommand:`revokeRolesFromUser` commands.
+To change a user's access, first determine the privileges the user needs and
+then determine the roles that grants those privileges. Grant and revoke roles
+using the method:`db.grantRolesToUser()` and :method:`db.revokeRolesFromUser`
+methods.
 
-For an overview of roles and privileges, see :ref:`authorization`.
+For an overview of roles and privileges, see :ref:`authorization`. For
+descriptions of the access each system role provides, see :ref:`system-defined
+roles <system-user-roles>`.
 
 Prerequisites
 -------------
@@ -25,6 +27,8 @@ Prerequisites
 
 .. include:: /includes/access-revoke-roles.rst
 
+.. include:: /includes/access-roles-info.rst
+
 Procedure
 ---------