DOCS-8620: multi-user authentication

Author: i80and

source/core/authentication.txt

@@ -25,11 +25,7 @@ verified user's access to resources and operations.
 Authentication Methods
 ----------------------
 
-To authenticate a :doc:`user </core/security-users>`, MongoDB provides the
-:method:`db.auth()` method.
-
-For the :binary:`~bin.mongo` shell and the MongoDB tools, you can also authenticate
-a user by passing in the user authentication information from the command line.
+.. include:: /includes/fact-authenticate.rst
 
 .. _available-authentication-mechanisms:
 
@@ -58,7 +54,7 @@ MongoDB supports multiple authentication mechanisms:
 In addition to supporting the aforementioned mechanisms, MongoDB Enterprise
 also supports the following mechanisms:
 
-- :ref:`LDAP proxy authentication <security-auth-ldap>`, and 
+- :ref:`LDAP proxy authentication <security-auth-ldap>`, and
 
 - :ref:`Kerberos authentication <security-auth-kerberos>`.
 
@@ -82,7 +78,7 @@ authentication and sharded clusters, see :ref:`sharding-security`.
 .. class:: hidden
 
    .. toctree::
-      :titlesonly: 
+      :titlesonly:
 
       /core/security-users
       /core/authentication-mechanisms

source/core/security-users.txt

@@ -42,8 +42,8 @@ Authentication Database
 When adding a user, you create the user in a specific database. This
 database is the authentication database for the user.
 
-A user can have privileges across different databases; i.e. a user's
-privileges are not limited to the authentication database. By assigning
+A user can have privileges across different databases; that is, a user's
+privileges are not limited to their authentication database. By assigning
 to the user roles in other databases, a user created in one database can
 have permissions to act on other databases. For more information on
 roles, see :doc:`/core/authorization`.
@@ -62,22 +62,7 @@ the user multiple times in different databases.
 Authenticate a User
 -------------------
 
-To authenticate a user, either
-
-- Use the command line authentication options (e.g. ``-u``, ``-p``,
-  ``--authenticationDatabase``) when connecting to the :binary:`~bin.mongod` or
-  :binary:`~bin.mongos` instance, or
-
-- Connect first to the :binary:`~bin.mongod` or :binary:`~bin.mongos` instance, and
-  then run the :dbcommand:`authenticate` command or the :method:`db.auth()`
-  method against the authentication database.
-
-To authenticate, the client must authenticate the user against the user's
-:ref:`authentication database <mongo-shell-authentication-options>`. 
-
-For instance, if using the :binary:`~bin.mongo` shell as a client, you can
-specify the authentication database for the user with the
-``--authenticationDatabase`` option.
+.. include:: /includes/fact-authenticate.rst
 
 Centralized User Data
 ---------------------
@@ -106,7 +91,7 @@ instance and add the users. Clients then authenticate these users through the
 :binary:`~bin.mongos` instances.
 
 .. versionchanged:: 2.6
-    
+
    MongoDB stores these sharded cluster user data in the ``admin`` database of
    the :term:`config servers <config server>`. Previously, the credentials for
    authenticating to a database on a sharded cluster resided on the

source/includes/fact-authenticate.rst

@@ -0,0 +1,29 @@
+To authenticate as a user, you must provide a username, password, and
+the :ref:`authentication database <mongo-shell-authentication-options>`
+associated with that user.
+
+To authenticate using the :binary:`~bin.mongo` shell, either:
+
+- Use the :binary:`~bin.mongo` command-line authentication options
+  (:option:`--username <mongo --username>`,
+  :option:`--password <mongo --password>`, and
+  :option:`--authenticationDatabase <mongo --authenticationDatabase>`)
+  when connecting to the :binary:`~bin.mongod` or
+  :binary:`~bin.mongos` instance, or
+
+- Connect first to the :binary:`~bin.mongod` or :binary:`~bin.mongos`
+  instance, and then run the :dbcommand:`authenticate` command or the
+  :method:`db.auth()` method against the :ref:`authentication database
+  <mongo-shell-authentication-options>`.
+
+  .. important::
+
+     Authenticating multiple times as different users does **not** drop
+     the credentials of previously-authenticated users. This may lead to
+     a connection having more permissions than intended by the user, and
+     causes operations within a
+     :doc:`logical session </reference/server-sessions>` to raise an
+     error.
+
+For examples of authenticating using a MongoDB driver, see the
+`driver documentation <https://docs.mongodb.com/ecosystem/drivers/>`__.