DOCS-2245 add grantPrivilegesToRole method

bin/builddata/htaccess-next.yaml

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

source/includes/access-grant-privileges.rst

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

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

@@ -18,11 +18,11 @@ file: /reference/method/db.dropAllRoles
 description: |
   Deletes all user-defined roles associated with a database.
 ---
-# name: :method:`db.grantPrivilegesToRole()`
-# file: /reference/method/db.grantPrivilegesToRole
-# description: |
-#   Assigns privileges to a user-defined role.
-# ---
+name: :method:`db.grantPrivilegesToRole()`
+file: /reference/method/db.grantPrivilegesToRole
+description: |
+  Assigns privileges to a user-defined role.
+---
 name: :method:`db.revokePrivilegesFromRole()`
 file: /reference/method/db.revokePrivilegesFromRole
 description: |

source/reference/command/grantPrivilegesToRole-field.yaml

@@ -1,3 +1,4 @@
+#content from this page is included in /reference/method/db.grantPrivilegesToRole-param.yaml
 object:
   name: grantPrivilegesToRole
   type: dbcommand
@@ -19,9 +20,8 @@ name: privileges
 type: array
 position: 2
 description: |
-  An array of privileges to add to the role. See
-  :data:`~admin.system.roles.privileges` for more information on the
-  format of the privileges.
+  The privileges to add to the role. For the format of a privilege, see
+  :data:`~admin.system.roles.privileges`.
 ---
 object:
   name: grantPrivilegesToRole

source/reference/command/grantPrivilegesToRole.txt

@@ -16,11 +16,14 @@ Definition
 
    .. code-block:: javascript
 
-      { grantPrivilegesToRole: "<role>",
+      { 
+        grantPrivilegesToRole: "<role>",
         privileges: [
-                      { resource: { <resource> }, actions: [ "<action>", ... ] },
-                      ...
-                    ],
+            {
+              resource: { <resource> }, actions: [ "<action>", ... ]
+            },
+            ...
+        ],
         writeConcern: { <write concern> }
       }
 
@@ -32,11 +35,7 @@ Definition
 Required Access
 ---------------
 
-To issue the :dbcommand:`grantPrivilegesToRole` command, a user must
-have access that includes the :authaction:`grantRole` action for the
-database the privilege targets. To grant a privilege on multiple
-databases or on the ``cluster`` resource, a user must have access that includes
-:authaction:`grantRole` action on the ``admin`` database.
+.. include:: /includes/access-grant-privileges.rst
 
 Example
 -------
@@ -49,8 +48,12 @@ database that the command is run:
 
    { grantPrivilegesToRole: "service",
      privileges: [
-       { resource: { db: "products", collection: "" }, actions: [ "find" ] },
-       { resource: { db: "", collection: "system.indexes" }, actions: [ "find" ] }
+         {
+           resource: { db: "products", collection: "" }, actions: [ "find" ]
+         },
+         {
+           resource: { db: "", collection: "system.indexes" }, actions: [ "find" ]
+         }
      ],
      writeConcern: { w: "majority" , wtimeout: 5000 }
    }

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

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

source/reference/method/db.grantPrivilegesToRole.txt

@@ -0,0 +1,82 @@
+==========================
+db.grantPrivilegesToRole()
+==========================
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.grantPrivilegesToRole ( rolename, privileges, writeConcern )
+
+   Grants additional privileges to a :ref:`user-defined
+   <user-defined-roles>` role.
+
+   The :method:`grantPrivilegesToRole()` method uses the following syntax:
+
+   .. code-block:: javascript
+
+      db.grantPrivilegesToRole(
+          "< rolename >",
+          [
+              { resource: { <resource> }, actions: [ "<action>", ... ] },
+              ...
+          ],
+          { < writeConcern > }
+      )
+
+   The :method:`grantPrivilegesToRole()` method takes the following arguments:
+
+   .. include:: /reference/method/db.grantPrivilegesToRole-param.rst
+
+   The :method:`grantPrivilegesToRole()` method can grant one or more
+   privileges. Each ``<privilege>`` has the following syntax:
+
+   .. code-block:: javascript
+
+      { resource: { <resource> }, actions: [ "<action>", ... ] }
+
+   .. |local-cmd-name| replace:: :method:`db.grantPrivilegesToRole()`
+
+   The :method:`db.grantPrivilegesToRole()` method wraps the
+   :dbcommand:`grantPrivilegesToRole` command.
+
+Required Access
+---------------
+
+.. include:: /includes/access-grant-privileges.rst
+
+Example
+-------
+
+The following :method:`db.grantPrivilegesToRole()` operation grants two
+additional privileges to the role ``inventoryCntrl01``, which exists on the
+``products`` database. The operation is run on that database:
+
+.. code-block:: javascript
+
+   db.grantPrivilegesToRole(
+     "inventoryCntrl01",
+     [
+       { 
+         resource: { db: "products", collection: "" },
+         actions: [ "insert" ]
+       },
+       {
+         resource: { db: "products", collection: "system.indexes" },
+         actions: [ "find" ]
+       }
+     ],
+     { w: "majority" }
+   )
+
+The first :ref:`resource document <resource-document>` allows users with
+this role to insert data in all collections on the ``products`` database,
+other than :doc:`system collections </reference/system-collections>`. Access
+to a system collection must be granted explicitly, as done by the second
+privilege.
+
+The second privilege explicitly grants read access to the system collection
+named :data:`system.indexes <<database>.system.indexes>`. The privilege
+grants the :authaction:`find` :ref:`action <security-user-actions>`, which
+allows users with this role to read the ``system.indexes`` collection.