DOCS-2332 add db.revokePrivilegesFromRole method

bin/builddata/htaccess-next.yaml

@@ -585,6 +585,14 @@ redirect-path: '/reference/method/db.getUsers'
 url-base: '/reference/security'
 type: 'redirect'
 code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/method/db.revokePrivilegesFromRole'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
 outputs:
   - 'manual'
   - 'before-v2.4'

source/includes/access-revoke-privileges.rst

@@ -0,0 +1,5 @@
+A user must have the :authaction:`revokeRole` :ref:`action
+<security-user-actions>` on the database a privilege targets in order to
+revoke that privilege. If the privilege targets multiple databases or the
+``cluster`` resource, a user must have the :authaction:`revokeRole` action
+on the ``admin`` database.

source/includes/ref-toc-method-role-management.yaml

@@ -23,11 +23,11 @@
 # description: |
 #   Assigns privileges to a user-defined role.
 # ---
-# name: :method:`db.revokePrivilegesFromRole()`
-# file: /reference/method/db.revokePrivilegesFromRole
-# description: |
-#   Removes the specified privileges from a user-defined role.
-# ---
+name: :method:`db.revokePrivilegesFromRole()`
+file: /reference/method/db.revokePrivilegesFromRole
+description: |
+  Removes the specified privileges from a user-defined role.
+---
 name: :method:`db.grantRolesToRole()`
 file: /reference/method/db.grantRolesToRole
 description: |

source/reference/command/revokePrivilegesFromRole-field.yaml

@@ -1,3 +1,4 @@
+#content from this page is included in /reference/method/db.revokePrivilegesFromRole-param.yaml
 object:
   name: revokePrivilegesFromRole
   type: dbcommand
@@ -20,7 +21,8 @@ name: privileges
 type: array
 position: 2
 description: |
-  An array of privileges to remove from the role.  See
+  An array of privileges to remove from the role. Each privilege must
+  exactly match an existing privilege. See
   :data:`~admin.system.roles.privileges` for more information on the
   format of the privileges.
 ---

source/reference/command/revokePrivilegesFromRole.txt

@@ -10,88 +10,106 @@ Definition
 .. dbcommand:: revokePrivilegesFromRole
 
    Removes the specified privileges from the :ref:`user-defined
-   <user-defined-roles>` role defined on the database where the
+   <user-defined-roles>` role on the database where the
    command is run. The :dbcommand:`revokePrivilegesFromRole` command
    has the following syntax:
 
    .. code-block:: javascript
 
-      { revokePrivilegesFromRole: "<role>",
-        privileges: [
-          { resource: { <resource> }, actions: [ "<action>", ... ] },
-          ...
-        ],
+      {
+        revokePrivilegesFromRole: "<role>",
+        privileges:
+            [
+              { resource: { <resource> }, actions: [ "<action>", ... ] },
+              ...
+            ],
         writeConcern: <write concern document>
       }
 
    The :dbcommand:`revokePrivilegesFromRole` command has the following fields:
 
    .. include:: /reference/command/revokePrivilegesFromRole-field.rst
 
-Required Access
----------------
-
-To revoke a privilege, a user must have :authaction:`revokeRole` access
-on the database the privilege targets. If the privilege targets multiple
-databases or the ``cluster`` resource, a user must have
-:authaction:`revokeRole` access on the ``admin`` database.
-
-Examples
+Behavior
 --------
 
-Match ``resource`` Patterns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 To revoke a privilege, you must match the :doc:`resource document
-</reference/resource-document>` pattern exactly. Consider a role
-``myRole`` with the following privilege that applies to the
-``products`` database:
+</reference/resource-document>` pattern exactly: the ``resource`` and
+``actions`` fields must exactly match an existing privilege. The
+:dbcommand:`revokePrivilegesFromRole` command *cannot* remove part of a
+privilege, such as a subset of the ``ressource`` document or ``actions``
+array. The method only removes the whole privilege.
 
-.. code-block:: javascript
+For example, given the role ``accountRole`` with the following privilege:
 
-   { resource: { db: "products", collection: "" },
-     actions: [ "find",  "update" ] }
+.. code-block:: javascript
 
-You cannot revoke ``find`` from just one collection in the
-``products`` database. Trying to remove the following would result in
-no change:
+    {
+        "resource" : {
+            "db" : "products",
+            "collection" : ""
+        },
+        "actions" : [
+            "find",
+            "update",
+        ]
+    }
+
+You *cannot* revoke ``find`` and ``update`` from just *one* collection
+instead of the whole ``products`` database, and you cannot revoke only the
+``find`` action and leave the ``update`` action. To revoke one resource or
+action, you must revoke the whole privilege:
 
 .. code-block:: javascript
 
-   db.runCommand ( { revokePrivilegesFromRole: "myRole",
-                     privileges: [
-                                  { resource: { db: "products", collection: "gadgets" },
-                                    actions: [ "find" ] }
-                                 ],
-                 } )
-
-To revoke ``find`` from the role ``myRole``, you must match the
-:doc:`resource document </reference/resource-document>` pattern exactly:
+   db.runCommand(
+       {
+         revokePrivilegesFromRole: "myRole",
+         privileges:
+           [
+             {
+               resource : {
+                   db : "products",
+                   collection : ""
+               },
+               actions : [
+                   "find",
+                   "update",
+               ]
+             }
+           ]
+       }
+   )
 
-.. code-block:: javascript
+Required Access
+---------------
 
-   db.runCommand ( { revokePrivilegesFromRole: "myRole",
-                     privileges: [
-                                   { resource: { db: "products", collection: "" },
-                                     actions: [ "find" ] }
-                                 ]
-                 } )
+.. include:: /includes/access-revoke-privileges.rst
 
-Remove Multiple Privileges
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example
+-------
 
-The following :dbcommand:`revokePrivilegesFromRole` operation
-removes ``find`` from the ``products`` database as well as from
-the ``system.indexes`` collections in all databases:
+The following operation removes a privilege from the ``associates`` role.
+The operation removes the privilege that grants the ``createCollection``,
+``createIndex``, and ``find`` :ref:`actions <security-user-actions>` on both
+the ``products`` and ``categories`` databases:
 
 .. code-block:: javascript
 
-   db.runCommand ( { revokePrivilegesFromRole: "associate",
-                     privileges: [
-                                   { resource: { db: "products", collection: "" },
-                                     actions: [ "find" ] },
-                                   { resource: { db: "", collection: "system.indexes" },
-                                     actions: [ "find" ] }
-                                 ],
-                     writeConcern: { w: "majority" , wtimeout: 5000 }
-                } )
+   db.runCommand(
+      {
+        revokePrivilegesFromRole: "associate",
+        privileges:
+         [
+           {
+             resource: { db: "products", collection: "" },
+             actions: [ "createCollection", "createIndex", "find" ]
+           },
+           {
+             resource: { db: "categories", collection: "" },
+             actions: [ "createCollection", "createIndex", "find" ]
+           }
+         ],
+        writeConcern: { w: "majority" }
+      }
+   )

source/reference/method/db.revokePrivilegesFromRole-param.yaml

@@ -0,0 +1,20 @@
+object:
+  name: db.revokePrivilegesFromRole
+  type: method
+field:
+  optional: false
+  type: param
+name: rolename
+type: string
+position: 1
+description: |
+  The name of the role from which to revoke privileges.
+---
+file: /reference/command/revokePrivilegesFromRole-field.yaml
+name: privileges
+position: 2
+---
+file: /reference/command/revokePrivilegesFromRole-field.yaml
+name: writeConcern
+position: 3
+...

source/reference/method/db.revokePrivilegesFromRole.txt

@@ -0,0 +1,116 @@
+=============================
+db.revokePrivilegesFromRole()
+=============================
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.revokePrivilegesFromRole ( rolename, privileges, writeConcern )
+
+   Removes the specified privileges from the :ref:`user-defined
+   <user-defined-roles>` role on the database where the method runs. The
+   :method:`revokePrivilegesFromRole` method has the following syntax:
+
+   .. code-block:: javascript
+
+      db.revokePrivilegesFromRole(
+          "<rolename>",
+          [
+              { resource: { <resource> }, actions: [ "<action>", ... ] },
+              ...
+          ],
+          { <writeConcern> }
+      )
+
+   The :method:`revokePrivilegesFromRole` method takes the following arguments:
+
+   .. include:: /reference/method/db.revokePrivilegesFromRole-param.rst
+
+   The :method:`db.revokePrivilegesFromRole()` method wraps the
+   :dbcommand:`revokePrivilegesFromRole` command.
+
+Behavior
+--------
+
+To revoke a privilege, you must match the :doc:`resource document
+</reference/resource-document>` pattern exactly: the ``resource`` and
+``actions`` fields must exactly match an existing privilege. The
+:method:`db.revokePrivilegesFromRole()` method *cannot* remove part of a
+privilege, such as a subset of the ``ressource`` document or ``actions``
+array. The method only removes the whole privilege.
+
+For example, given the role ``accountRole`` with the following privilege:
+
+.. code-block:: javascript
+
+    {
+        "resource" : {
+            "db" : "products",
+            "collection" : ""
+        },
+        "actions" : [
+            "find",
+            "update",
+        ]
+    }
+
+You *cannot* revoke ``find`` and ``update`` from just *one* collection
+instead of the whole ``products`` database, and you cannot revoke only the
+``find`` action and leave the ``update`` action. To revoke one resource or
+action, you must revoke the whole privilege:
+
+.. code-block:: javascript
+
+   db.revokePrivilegesFromRole(
+       {
+         "myRole",
+         privileges:
+           [
+             {
+               resource : {
+                   db : "products",
+                   collection : ""
+               },
+               actions : [
+                   "find",
+                   "update",
+               ]
+             }
+           ]
+       }
+   )
+
+Required Access
+---------------
+
+.. include:: /includes/access-revoke-privileges.rst
+
+Example
+-------
+
+The following operation removes a privilege from the ``associates`` role.
+The operation removes the privilege that grants the ``createCollection``,
+``createIndex``, and ``find`` :ref:`actions <security-user-actions>` on both
+the ``products`` and ``categories`` databases:
+
+.. code-block:: javascript
+
+   db.revokePrivilegesFromRole(
+      {
+        "associate",
+        privileges:
+         [
+           {
+             resource: { db: "products", collection: "" },
+             actions: [ "createCollection", "createIndex", "find" ]
+           },
+           {
+             resource: { db: "categories", collection: "" },
+             actions: [ "createCollection", "createIndex", "find" ]
+           }
+         ],
+        writeConcern: { w: "majority" }
+      }
+   )