DOCS-12141: listDatabases authorizedDatabases

Author: Kay Kim

source/includes/apiargs-dbcommand-listDatabases-field.yaml

@@ -36,6 +36,24 @@ description: |
 
    .. versionadded:: 3.6
 
+interface: dbcommand
+operation: listDatabases
+arg_name: field
+optional: true
+---
+name: authorizedDatabases
+type: boolean
+description: |
+
+   A flag that determines which databases are returned based on the
+   user privileges when access control is enabled.
+
+   .. include:: /includes/extracts/listDatabases-auth-privileges.rst
+
+   For more information, see :ref:`listDatabases-behavior`.
+
+   .. versionadded:: 4.0.5
+
 interface: dbcommand
 operation: listDatabases
 arg_name: field

source/includes/extracts-listDatabases-auth.yaml

@@ -0,0 +1,48 @@
+ref: listDatabases-auth-privileges
+content: |
+
+   - If ``authorizedDatabases`` is unspecified, and
+   
+     - If the user has :authaction:`listDatabases` action on the
+       cluster resource, :dbcommand:`listDatabases` command returns all
+       databases.
+      
+     - If the user does not have :authaction:`listDatabases` action on
+       the cluster, :dbcommand:`listDatabases` command returns only the
+       databases for which the user has the :authaction:`find` action
+       on the database resource (and not the collection resource).
+
+   - If ``authorizedDatabases`` is ``true``, :dbcommand:`listDatabases`
+     command returns only the databases for which the user has the
+     :authaction:`find` action on the database resource (and not the
+     collection resource).
+   
+
+   - If ``authorizedDatabases`` is ``false``, and
+   
+     - If the user has :authaction:`listDatabases` action on the
+       cluster, :dbcommand:`listDatabases` command returns all databases
+
+     - If the user does not have :authaction:`listDatabases` action on
+       the cluster, :dbcommand:`listDatabases` command errors with
+       insufficient permissions.
+       
+---
+ref: listDatabases-auth-4.0.0-4.0.4
+content: |
+   For MongoDB 4.0.0-4.0.4:
+      If the user does not have the :authaction:`listDatabases`
+      privilege action, users can run the :dbcommand:`listDatabases`
+      command to return a list of databases for which the user has the
+      :authaction:`find` action privilege.
+---
+ref: listDatabases-auth-4.0.5
+content: |
+   For MongoDB 4.0.5+:
+      If the user does not have the :authaction:`listDatabases`
+      privilege action, users can run the :dbcommand:`listDatabases`
+      command to return a list of databases for which the user has the
+      :authaction:`find` action privilege if the command is run with
+      ``authorizedDatabases`` option unspecified or set to ``true``.
+   
+...

source/reference/built-in-roles.txt

@@ -61,12 +61,9 @@ Every database includes the following client roles:
    - :authaction:`listIndexes`
    - :authaction:`listCollections`
 
-   .. versionchanged:: 4.0
-
-      If the user does not have the :authaction:`listDatabases`
-      privilege action, users can run the :dbcommand:`listDatabases`
-      command to return a list of databases for which the user has the
-      :authaction:`find` action privilege.
+   .. include:: /includes/extracts/listDatabases-auth-4.0.0-4.0.4.rst
+   
+   .. include:: /includes/extracts/listDatabases-auth-4.0.5.rst
 
 .. authrole:: readWrite
 

source/reference/command/listDatabases.txt

@@ -30,8 +30,6 @@ Definition
    The :dbcommand:`listDatabases` command can take the following
    optional fields:
 
-   .. versionchanged:: 4.0
-
    .. include:: /includes/apiargs/dbcommand-listDatabases-field.rst
 
 Output
@@ -55,24 +53,33 @@ Output
 - A field named ``totalSize`` whose value is the sum of all the
   ``sizeOnDisk`` fields in bytes.
 
+.. _listDatabases-behavior:
+
 Behavior
 --------
 
-.. versionchanged:: 4.0
+When :doc:`authentication </core/authentication>` is enabled:
+
+- For MongoDB 4.0.5+:
+   The :dbcommand:`listDatabases` command returns different values
+   based on the privileges assigned to the user who
+   executes the command and the ``authorizedDatabases`` command option:
 
-   When :doc:`authentication </core/authentication>` is enabled, the
-   :dbcommand:`listDatabases` command returns different values based on
-   the :doc:`privilege actions </reference/privilege-actions/>`
-   assigned to the user who executes the command.
+   .. include:: /includes/extracts/listDatabases-auth-privileges.rst
 
-   - If the user has the :authaction:`listDatabases` privilege action,
-     the :dbcommand:`listDatabases` command returns a list of all
-     existing databases.
+- For MongoDB 4.0.0-4.0.4:
+   The :dbcommand:`listDatabases` command returns different values
+   based on the privileges assigned to the user who
+   executes the command.
+
+   - If the user has the :authaction:`listDatabases` privilege action
+     on the cluster, the :dbcommand:`listDatabases` command returns a
+     list of all existing databases.
 
    - If the user does not have the :authaction:`listDatabases`
-     privilege action, the :dbcommand:`listDatabases` command only
-     returns a list of databases for which the user has the
-     :authaction:`find` action privilege.
+     privilege action on the cluster, the :dbcommand:`listDatabases`
+     command only returns a list of databases for which the user has
+     the :authaction:`find` action.
 
 Examples
 --------
@@ -217,3 +224,5 @@ For example:
    }
 
 .. seealso:: :doc:`/tutorial/use-database-commands`.
+
+.. |checkmark| unicode:: U+2713

source/reference/privilege-actions.txt

@@ -64,12 +64,9 @@ Query and Write Actions
    and :dbcommand:`renameCollection` commands and the
    :method:`db.collection.renameCollection()` helper method.
 
-   .. versionchanged:: 4.0
-
-      If a user running the :dbcommand:`listDatabases` command does not
-      have the :authaction:`listDatabases` privilege action, the command
-      returns a list of databases for which the user has the
-      :authaction:`find` privilege action.
+   .. include:: /includes/extracts/listDatabases-auth-4.0.0-4.0.4.rst
+   
+   .. include:: /includes/extracts/listDatabases-auth-4.0.5.rst
 
    Apply this action to database or collection resources.
 
@@ -711,13 +708,9 @@ Diagnostic Actions
    User can perform the :dbcommand:`listDatabases` command. Apply this
    action to the ``cluster`` resource.
 
-   .. versionchanged:: 4.0
-
-      If a user running the :dbcommand:`listDatabases` command does
-      not have the :authaction:`listDatabases` privilege action, the
-      :dbcommand:`listDatabases` command only returns a list of
-      databases for which the user has the :authaction:`find` action
-      privilege.
+   .. include:: /includes/extracts/listDatabases-auth-4.0.0-4.0.4.rst
+   
+   .. include:: /includes/extracts/listDatabases-auth-4.0.5.rst
 
 .. authaction:: listCollections