(DOCS-11283): Document showAuthenticationRestrictions option for roles (#2195) (#2205)

* Add examples to db.getRole()

* update getRoles rolesInfo command

* add examples for rolesInfo command

* add replacement

* alphabetize

* minimalism

* tweaks

* fix build warning

* add example section lead-ins

* wording

Author: jeff-allen-mongo

source/includes/fact-show-auth-restrictions-description.rst

@@ -0,0 +1,7 @@
+Optional. Set this field to ``true`` to include :ref:`authentication
+restrictions <create-role-auth-restrictions>` in the output.
+Authentication restrictions indicate the IP addresses that users with
+this role can connect to and from.
+
+By default, this field is ``false``, meaning that the |getRoleMethod|
+output does not include authentication restrictions.

source/reference/command/createRole.txt

@@ -125,6 +125,8 @@ Roles
 
 .. include:: /includes/fact-roles-array-contents.rst
 
+.. _create-role-auth-restrictions:
+
 Authentication Restrictions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/reference/command/rolesInfo.txt

@@ -7,12 +7,14 @@ rolesInfo
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Definition
 ----------
 
+.. |getRoleMethod| replace:: ``rolesInfo``
+
 .. dbcommand:: rolesInfo
 
    Returns inheritance and privilege information for specified roles,
@@ -28,63 +30,54 @@ Definition
 
       { 
         rolesInfo: { role: <name>, db: <db> },
-        showPrivileges: <Boolean>,
+        showAuthenticationRestrictions: <Boolean>,
         showBuiltinRoles: <Boolean>,
+        showPrivileges: <Boolean>,
         comment: <any>
       }
 
    :dbcommand:`rolesInfo` has the following fields:
 
 
-   .. list-table::
-      :header-rows: 1
-      :widths: 20 20 80
-   
-      * - Field
-   
-        - Type
-   
-        - Description
-   
-      * - ``rolesInfo``
-   
-        - string, document, array,  or integer
-   
-        - The role(s) to return information about. For the syntax for specifying
-          roles, see :ref:`rolesinfo-behavior`.
-          
-          
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+ 
+   * - Field
+     - Type
+     - Description
+ 
+   * - ``rolesInfo``
+     - string, document, array,  or integer
+     - The role(s) to return information about. For the syntax for specifying
+       roles, see :ref:`rolesinfo-behavior`.
 
-      * - ``showPrivileges``
-   
-        - boolean
-   
-        - Optional. Set the field to ``true`` to show role privileges, including both privileges
-          inherited from other roles and privileges defined directly. By default, the
-          command returns only the roles from which this role inherits privileges and
-          does not return specific privileges.
-          
-          
-   
-      * - ``showBuiltinRoles``
-   
-        - boolean
-   
-        - Optional. When the ``rolesInfo`` field is set to ``1``, set ``showBuiltinRoles`` to
-          ``true`` to include :ref:`built-in roles <built-in-roles>` in the output.
-          By default this field is set to ``false``, and the output for ``rolesInfo:
-          1`` displays only :ref:`user-defined roles <user-defined-roles>`.
-          
-          
-   
-      * - ``comment``
-
-        - any
-
-        - .. include:: /includes/extracts/comment-content.rst
+   * - ``showAuthenticationRestrictions``
+     - boolean
+     - .. include:: /includes/fact-show-auth-restrictions-description.rst
+
+   * - ``showBuiltinRoles``
+     - boolean
+     - Optional. When the ``rolesInfo`` field is set to ``1``, set
+       ``showBuiltinRoles`` to ``true`` to include :ref:`built-in roles
+       <built-in-roles>` in the output. By default, this field is set to
+       ``false``, and the output for ``rolesInfo: 1`` displays only
+       :ref:`user-defined roles <user-defined-roles>`.
 
-          .. versionadded:: 4.4
-
+   * - ``showPrivileges``
+     - boolean
+     - Optional. Set the field to ``true`` to show role privileges,
+       including both privileges inherited from other roles and
+       privileges defined directly. By default, the command returns only
+       the roles from which this role inherits privileges and does not
+       return specific privileges.
+       
+   * - ``comment``
+     - any
+     - .. include:: /includes/extracts/comment-content.rst
+    
+       .. versionadded:: 4.4
+ 
 .. _rolesinfo-behavior:
 
 Behavior
@@ -202,6 +195,21 @@ Output
 Examples
 --------
 
+The examples in this section show how to use the ``rolesInfo`` command
+to:
+
+- :ref:`rolesInfo-example-single-role`
+
+- :ref:`rolesInfo-example-multiple-roles`
+
+- :ref:`rolesInfo-example-user-defined-roles`
+
+- :ref:`rolesInfo-example-user-defined-and-built-in-roles`
+
+- :ref:`rolesInfo-example-auth-restrictions`
+
+.. _rolesInfo-example-single-role:
+
 View Information for a Single Role
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -239,8 +247,10 @@ for the role ``associate`` defined on the ``products`` database:
        }
    )
 
-View Information for Several Roles
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _rolesInfo-example-multiple-roles:
+
+View Information for Multiple Roles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following command returns information for two roles on two different
 databases:
@@ -270,6 +280,8 @@ The following returns *both* the role inheritance and the privileges:
        }
    )
 
+.. _rolesInfo-example-user-defined-roles:
+
 View All User-Defined Roles for a Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -286,6 +298,49 @@ privileges:
        }
    )
 
+Example output (shortened for readability):
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+     roles: [
+       {
+         _id: 'products.associate',
+         role: 'associate',
+         db: 'products',
+         privileges: [
+           {
+             resource: { db: 'products', collection: '' },
+             actions: [ 'bypassDocumentValidation' ]
+           }
+         ],
+         roles: [ { role: 'readWrite', db: 'products' } ],
+         isBuiltin: false,
+         inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
+         inheritedPrivileges: [
+           {
+             resource: { db: 'products', collection: '' },
+             actions: [ 'bypassDocumentValidation' ]
+           },
+           {
+             resource: { db: 'products', collection: '' },
+             actions: [
+               'changeStream',
+               'collStats',
+               'compactStructuredEncryptionData',
+               ...
+             ]
+           },
+           ...
+         ]
+       }
+     ],
+     ok: 1
+   }
+
+.. _rolesInfo-example-user-defined-and-built-in-roles:
+
 View All User-Defined and Built-In Roles for a Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -300,3 +355,78 @@ runs, including both built-in and user-defined roles:
          showBuiltinRoles: true
        }
    )
+
+Example output (shortened for readability):
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+     roles: [
+       {
+         role: 'enableSharding',
+         db: 'products',
+         isBuiltin: true,
+         roles: [],
+         inheritedRoles: []
+       },
+       {
+         role: 'userAdmin',
+         db: 'products',
+         isBuiltin: true,
+         roles: [],
+         inheritedRoles: []
+       },
+       {
+         role: 'read',
+         db: 'products',
+         isBuiltin: true,
+         roles: [],
+         inheritedRoles: []
+       },
+       ...
+     ],
+     ok: 1
+   }
+
+.. _rolesInfo-example-auth-restrictions:
+
+View Authentication Restrictions for Roles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following operation returns all user-defined roles on the
+``products`` database and includes authentication restrictions:
+
+.. code-block:: javascript
+
+   db.runCommand(
+       {
+         rolesInfo: 1,
+         showAuthenticationRestrictions: true
+       }
+   )
+
+Example output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+     roles: [
+       {
+         _id: 'products.associate',
+         role: 'associate',
+         db: 'products',
+         roles: [ { role: 'readWrite', db: 'products' } ],
+         authenticationRestrictions: [
+           [ { clientSource: [ '198.51.100.0' ] } ]
+         ],
+         isBuiltin: false,
+         inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
+         inheritedAuthenticationRestrictions: [
+           [ { clientSource: [ '198.51.100.0' ] } ]
+         ]
+       }
+     ],
+     ok: 1
+   }