DOCSP-18010: Refactor Authentication mechanisms

Author: npentrel

snooty.toml

@@ -67,6 +67,7 @@ toc_landing_pages = [
    "/core/security-hardening",
    "/core/security-internal-authentication",
    "/core/security-ldap",
+   "/core/security-scram",
    "/core/security-transport-encryption",
    "/core/security-users",
    "/core/security-x.509",

source/core/authentication-mechanisms.txt

@@ -12,14 +12,10 @@ Authentication Mechanisms
    :depth: 1
    :class: singlecol
 
-.. note::
-
-   Starting in version 4.0, MongoDB removes support for the deprecated
-   MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism.
 
 MongoDB supports the following authentication mechanisms:
 
-- :doc:`/core/security-scram` (*Default*)
+- :doc:`SCRAM Authentication </core/security-scram>` (*Default*)
 
 - :doc:`x.509 Certificate Authentication </core/security-x.509>`.
 
@@ -30,24 +26,36 @@ authentication mechanisms supported by MongoDB Enterprise.
 
 .. _authentication-mechanism-default:
 
-Default Authentication Mechanism
---------------------------------
+SCRAM Authentication
+--------------------
+
+Salted Challenge Response Authentication Mechanism (SCRAM) is the
+default authentication mechanism for MongoDB.
 
-As of MongoDB 3.0, :ref:`Salted Challenge Response Authentication
-Mechanism (SCRAM) <authentication-scram>` is the default
-authentication mechanism for MongoDB.
+For more information on SCRAM and MongoDB, see:
 
+- :doc:`SCRAM Authentication </core/security-scram>`
+- :ref:`scram-client-authentication`
 
-Specify Authentication Mechanism
+.. _authentication-mechanism-x509:
+
+x.509 Certificate Authentication
 --------------------------------
 
-To specify the authentication mechanism to use, set the
-:parameter:`authenticationMechanisms` parameter for :binary:`~bin.mongod` and
-:binary:`~bin.mongos`.
+MongoDB supports x.509 certificate authentication for client
+authentication and internal authentication of the members of replica
+sets and sharded clusters. x.509 certificate authentication requires a
+secure :doc:`TLS/SSL connection </tutorial/configure-ssl>`.
+
+To use MongoDB with x.509, you must use valid certificates generated and
+signed by a certificate authority. The client x.509 certificates
+must meet the :ref:`client certificate requirements
+<client-x509-certificates-requirements>`.
+
+For more information on x.509 and MongoDB, see:
 
-Clients specify the authentication mechanism in the :method:`db.auth()` method.
-For :binary:`~bin.mongosh` and the MongoDB tools, you can also specify the
-authentication mechanism from the command line.
+- :doc:`x.509 Certificate Authentication </core/security-x.509>`
+- :ref:`x509-client-authentication`
 
 .. toctree::
    :titlesonly:

source/core/security-internal-authentication.txt

@@ -67,7 +67,7 @@ For example,
 .. tabs::
 
    tabs:
-   
+
       - id: single-key
         name: Single key
         content: |
@@ -175,10 +175,10 @@ see :doc:`/tutorial/upgrade-keyfile-to-x509`.
    /tutorial/deploy-replica-set-with-keyfile-access-control
    /tutorial/enforce-keyfile-access-control-in-existing-replica-set
    /tutorial/enforce-keyfile-access-control-in-existing-replica-set-without-downtime
-   /tutorial/rotate-key-replica-set
    /tutorial/deploy-sharded-cluster-with-keyfile-access-control
    /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster
    /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime
+   /tutorial/rotate-key-replica-set
    /tutorial/rotate-key-sharded-cluster
    /tutorial/configure-x509-member-authentication
    /tutorial/upgrade-keyfile-to-x509

source/core/security-scram.txt

@@ -1,7 +1,5 @@
 .. _authentication-scram:
 
-
-
 =====
 SCRAM
 =====
@@ -14,46 +12,32 @@ SCRAM
    :depth: 1
    :class: singlecol
 
-.. note::
+Salted Challenge Response Authentication Mechanism (SCRAM) is the
+default authentication mechanism for MongoDB.
 
-   Starting in version 4.0, MongoDB removes support for the deprecated
-   MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism.
+When a user :ref:`authenticates <authentication-auth-as-user>`
+themselves, MongoDB uses SCRAM to verify the supplied user credentials
+against the user's :data:`name <admin.system.users.user>`,
+:data:`password <admin.system.users.credentials>` and
+:data:`authentication database <admin.system.users.db>`.
 
-   If your deployment has user credentials stored in ``MONGODB-CR``
-   schema, you must upgrade to SCRAM **before** you upgrade to version
-   4.0. For information on upgrading to ``SCRAM``, see
-   :doc:`/release-notes/3.0-scram`.
-
-Salted Challenge Response Authentication Mechanism (SCRAM) is the
-default authentication mechanism for MongoDB. SCRAM is based on the
-IETF `RFC 5802 <https://tools.ietf.org/html/rfc5802>`_ standard that
-defines best practices for implementation of challenge-response
-mechanisms for authenticating users with passwords.
-
-Using SCRAM, MongoDB verifies the supplied user credentials against the
-user's :data:`name <admin.system.users.user>`, :data:`password
-<admin.system.users.credentials>` and :data:`authentication database
-<admin.system.users.db>`. The authentication database is the database
-where the user was created, and together with the user's name, serves
-to identify the user.
+SCRAM is based on the IETF `RFC 5802
+<https://tools.ietf.org/html/rfc5802>`_ standard that defines best
+practices for the implementation of challenge-response mechanisms for
+authenticating users with passwords.
 
 .. _authentication-scram-sha-1:
-
 .. _authentication-scram-sha-256:
-
 .. _scram-features:
 
 Features
 --------
 
 MongoDB's implementation of SCRAM provides:
 
-- A tunable work factor (i.e. the iteration count),
-
-- Per-user random salts, and
-
-- Authentication of the server to the client as well as the client to the
-  server.
+- A tunable work factor (the iteration count)
+- Per-user random salts
+- Bi-directional authentication between server and client
 
 .. _scram-mechanisms:
 
@@ -69,35 +53,34 @@ MongoDB supports the following SCRAM mechanisms:
    * - SCRAM Mechanism
      - Description
 
-   * - ``SCRAM-SHA-1`` 
+   * - ``SCRAM-SHA-1``
 
      - Uses the SHA-1 hashing function.
 
        To modify the iteration count for ``SCRAM-SHA-1``, see
        :parameter:`scramIterationCount`.
 
-   * - ``SCRAM-SHA-256`` 
+   * - ``SCRAM-SHA-256``
 
-     - Uses the SHA-256 hashing function and requires
-       featureCompatibilityVersion (``fcv``) set to ``4.0``.
+     - Uses the SHA-256 hashing function.
 
        To modify the iteration count for ``SCRAM-SHA-256``, see
        :parameter:`scramSHA256IterationCount`.
 
-       .. versionadded:: 4.0
 
-When creating or updating a SCRAM user, you can indicate the specific
-SCRAM mechanism as well as indicate whether the server or the client
-digests the password. When using ``SCRAM-SHA-256``, MongoDB requires
-server-side password hashing, i.e. the server digests the password. For
-details, see :method:`db.createUser()` and :method:`db.updateUser()`.
+When you create or update a SCRAM user, you can indicate:
+
+- the SCRAM mechanism to use
+- whether the server or the client digests the password
+
+When you use ``SCRAM-SHA-256``, MongoDB requires server-side password
+hashing, which means that the server digests the password. For more
+information, see :method:`db.createUser()` and
+:method:`db.updateUser()`.
 
 Driver Support
 --------------
 
-To use SCRAM, you must upgrade your driver if your current driver
-version does not support ``SCRAM``.
-
 The minimum driver versions that support ``SCRAM`` are:
 
 .. |driver-compatibility-heading| replace:: Version
@@ -107,12 +90,16 @@ The minimum driver versions that support ``SCRAM`` are:
 Additional Information
 ----------------------
 
-- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM
-  Explained (Part 1)
+- `Blog Post: Improved Password-Based Authentication: SCRAM Explained (Part 1)
   <https://www.mongodb.com/blog/post/improved-password-based-authentication-mong
   odb-30-scram-explained-part-1?tck=docs_server>`_
 
-- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM
-  Explained (Part 2)
+- `Blog Post: Improved Password-Based Authentication: SCRAM Explained (Part 2)
   <https://www.mongodb.com/blog/post/improved-password-based-authentication-mong
   odb-30-scram-explained-part-2?tck=docs_server>`_
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   /tutorial/configure-scram-client-authentication

source/core/security-x.509.txt

@@ -12,17 +12,12 @@ x.509
    :depth: 1
    :class: singlecol
 
-MongoDB supports x.509 certificate authentication for client authentication and
-internal authentication of the members of replica sets and sharded clusters.
+MongoDB supports x.509 certificate authentication for client
+authentication and internal authentication of the members of replica
+sets and sharded clusters.
 
-x.509 certificate authentication requires a secure :doc:`TLS/SSL connection
-</tutorial/configure-ssl>`.
-
-.. note::
-
-   .. include:: /includes/fact-tls-1.0.rst
-
-.. |binary| replace:: MongoDB
+x.509 certificate authentication requires a secure :doc:`TLS/SSL
+connection </tutorial/configure-ssl>`.
 
 Certificate Authority
 ---------------------
@@ -37,6 +32,8 @@ Client x.509 Certificates
 To authenticate to servers, clients can use x.509 certificates instead
 of usernames and passwords.
 
+.. _client-x509-certificates-requirements:
+
 Client Certificate Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -49,63 +46,21 @@ MongoDB User and ``$external`` Database
 
 To authenticate with a client certificate, you must first add the value
 of the ``subject`` from the client certificate as a MongoDB user. Each
-unique x.509 client certificate corresponds to a single MongoDB user;
-i.e. you cannot use a single client certificate to authenticate more
-than one MongoDB user.
+unique x.509 client certificate corresponds to a single MongoDB user.
+You cannot use a single client certificate to authenticate more than one
+MongoDB user.
 
-Add the user in the ``$external`` database; i.e. the
-:ref:`authentication-database` is the ``$external`` database
+Add the user in the ``$external`` database. The ``$external`` database
+is the :ref:`authentication-database` for the user.
 
 .. include:: /includes/extracts/sessions-external-username-limit.rst
 
-Authenticate
-~~~~~~~~~~~~
-
-To connect and authenticate using x.509 client certificate:
-
-- For MongoDB 4.2 or greater, include the following options for the client:
-
-  - :option:`--tls <mongosh --tls>` (or the deprecated ``--ssl`` option)
-
-  - :option:`--tlsCertificateKeyFile <mongosh --tlsCertificateKeyFile>`
-    (or the deprecated ``--sslPEMKeyFile`` option)
-    
-  - :option:`--tlsCertificateKeyFilePassword <mongosh --tlsCertificateKeyFile>`
-    (or the deprecated ``--sslPEMKeyPassword`` option) if the
-    certificate key file is encrypted
-    
-  - :option:`--authenticationDatabase '$external' 
-    <mongosh --authenticationDatabase>`
-
-  - :option:`--authenticationMechanism MONGODB-X509 
-    <mongosh --authenticationMechanism>`
-
-- For MongoDB 4.0 and earlier, include the following options for the client:
-
-  - ``--ssl``
-
-  - ``--sslPEMKeyFile``
-
-  - ``--sslPEMKeyPassword`` option if
-    the ``--sslPEMKeyFile`` is encrypted.
-
-  - :option:`--authenticationDatabase '$external' 
-    <mongosh --authenticationDatabase>`
-
-  - :option:`--authenticationMechanism MONGODB-X509 <mongosh --authenticationMechanism>`
-
-You can also make the TLS/SSL connection first, and then use
-:method:`db.auth()` in the ``$external`` database to authenticate.
-
-For examples of both cases, see the :ref:`authenticate-with-x509-cert`
-section in :doc:`/tutorial/configure-x509-client-authentication`
-
 Member x.509 Certificates
---------------------------
+-------------------------
 
-For internal authentication, members of sharded clusters and replica sets
-can use x.509 certificates instead of keyfiles, which use the
-:doc:`/core/security-scram` authentication mechanism.
+For internal authentication between members of sharded clusters and
+replica sets you can use x.509 certificates instead of keyfiles, which
+use the :doc:`/core/security-scram` authentication mechanism.
 
 .. _x509-member-certificate-requirements:
 
@@ -119,12 +74,6 @@ MongoDB Configuration for Membership Authentication
 
 .. include:: /includes/extracts/x509-member-auth-configuration.rst
 
-Next Steps
-~~~~~~~~~~
-
-For an example of x.509 internal authentication, see
-:doc:`/tutorial/configure-x509-member-authentication`.
-
 .. toctree::
    :titlesonly:
    :hidden:

source/includes/extracts-ssl-facts.yaml

@@ -1,13 +1,11 @@
 ref: ssl-facts-x509-invalid-certificate
 content: |
 
-   Starting in MongoDB 4.0, if you specify
-   ``--sslAllowInvalidCertificates`` or
-   ``net.ssl.allowInvalidCertificates: true`` (or in MongoDB 4.2, the
-   alias ``--tlsAllowInvalidateCertificates`` or
-   ``net.tls.allowInvalidCertificates: true``) when using x.509
+   Starting in MongoDB 4.2, if you specify
+   ``--tlsAllowInvalidateCertificates`` or
+   ``net.tls.allowInvalidCertificates: true`` when using x.509
    authentication, an invalid certificate is only sufficient to
-   establish a TLS/SSL connection but is *insufficient* for
+   establish a TLS connection but it is *insufficient* for
    authentication.
 
 ---
@@ -28,10 +26,8 @@ ref: ssl-facts-x509-ca-file
 content: |
 
    To use x.509 authentication, ``--tlsCAFile`` or ``net.tls.CAFile``
-   must be specified unless using ``--tlsCertificateSelector`` or
-   ``--net.tls.certificateSelector``. Or if using the ``ssl`` aliases,
-   ``--sslCAFile`` or ``net.ssl.CAFile`` must be specified unless using
-   ``--sslCertificateSelector`` or ``net.ssl.certificateSelector``.
+   must be specified unless you are using ``--tlsCertificateSelector``
+   or ``--net.tls.certificateSelector``.
 
 ---
 ref: ssl-facts-see-more