From 2d30121019fbd17c5c4c7d561e9361ef632aa3e7 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 26 Aug 2021 14:10:58 +0200 Subject: [PATCH] DOCSP-18010: Refactor Authentication mechanisms --- snooty.toml | 1 + source/core/authentication-mechanisms.txt | 42 +- .../core/security-internal-authentication.txt | 4 +- source/core/security-scram.txt | 81 ++- source/core/security-x.509.txt | 83 +-- source/includes/extracts-ssl-facts.yaml | 16 +- .../includes/extracts-x509-certificate.yaml | 137 ++--- .../fact-ssl-certificate-authorities.rst | 6 +- .../list-table-3.0-driver-compatibility.rst | 38 +- .../steps-use-x509-authentication.yaml | 268 +++++++++ .../configure-scram-client-authentication.txt | 32 ++ .../configure-x509-client-authentication.txt | 508 +----------------- source/tutorial/enable-authentication.txt | 33 +- 13 files changed, 499 insertions(+), 750 deletions(-) create mode 100644 source/includes/steps-use-x509-authentication.yaml create mode 100644 source/tutorial/configure-scram-client-authentication.txt diff --git a/snooty.toml b/snooty.toml index 5a1fdd37092..ba63cbbb6e9 100644 --- a/snooty.toml +++ b/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", diff --git a/source/core/authentication-mechanisms.txt b/source/core/authentication-mechanisms.txt index 2a58a277451..88166e441cf 100644 --- a/source/core/authentication-mechanisms.txt +++ b/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 ` (*Default*) - :doc:`x.509 Certificate Authentication `. @@ -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) ` is the default -authentication mechanism for MongoDB. +For more information on SCRAM and MongoDB, see: +- :doc:`SCRAM Authentication ` +- :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 `. + +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 +`. + +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 ` +- :ref:`x509-client-authentication` .. toctree:: :titlesonly: diff --git a/source/core/security-internal-authentication.txt b/source/core/security-internal-authentication.txt index 2066e0c73d7..bb1b0634f27 100644 --- a/source/core/security-internal-authentication.txt +++ b/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 diff --git a/source/core/security-scram.txt b/source/core/security-scram.txt index aea924f3d1b..dbab88bcbff 100644 --- a/source/core/security-scram.txt +++ b/source/core/security-scram.txt @@ -1,7 +1,5 @@ .. _authentication-scram: - - ===== SCRAM ===== @@ -14,33 +12,22 @@ 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 ` +themselves, MongoDB uses SCRAM to verify the supplied user credentials +against the user's :data:`name `, +:data:`password ` and +:data:`authentication database `. - 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 `_ 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 `, :data:`password -` and :data:`authentication database -`. 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 +`_ 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 @@ -48,12 +35,9 @@ 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) `_ -- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM - Explained (Part 2) +- `Blog Post: Improved Password-Based Authentication: SCRAM Explained (Part 2) `_ + +.. toctree:: + :titlesonly: + :hidden: + + /tutorial/configure-scram-client-authentication diff --git a/source/core/security-x.509.txt b/source/core/security-x.509.txt index 7c6b127b030..fb55f75a576 100644 --- a/source/core/security-x.509.txt +++ b/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 -`. - -.. note:: - - .. include:: /includes/fact-tls-1.0.rst - -.. |binary| replace:: MongoDB +x.509 certificate authentication requires a secure :doc:`TLS/SSL +connection `. 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 ` (or the deprecated ``--ssl`` option) - - - :option:`--tlsCertificateKeyFile ` - (or the deprecated ``--sslPEMKeyFile`` option) - - - :option:`--tlsCertificateKeyFilePassword ` - (or the deprecated ``--sslPEMKeyPassword`` option) if the - certificate key file is encrypted - - - :option:`--authenticationDatabase '$external' - ` - - - :option:`--authenticationMechanism MONGODB-X509 - ` - -- 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' - ` - - - :option:`--authenticationMechanism MONGODB-X509 ` - -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: diff --git a/source/includes/extracts-ssl-facts.yaml b/source/includes/extracts-ssl-facts.yaml index 22bc149360e..3304090e1a1 100644 --- a/source/includes/extracts-ssl-facts.yaml +++ b/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 diff --git a/source/includes/extracts-x509-certificate.yaml b/source/includes/extracts-x509-certificate.yaml index 81736beabd9..f34f1411057 100644 --- a/source/includes/extracts-x509-certificate.yaml +++ b/source/includes/extracts-x509-certificate.yaml @@ -1,7 +1,7 @@ ref: x509-certificate-client content: | - The client certificate must have the following - properties: + + Client certificates must have the following properties: - A single Certificate Authority (CA) must issue the certificates for both the client and the server. @@ -16,65 +16,63 @@ content: | - Each unique MongoDB user must have a unique certificate. - A client x.509 certificate's subject, which contains the - Distinguished Name (``DN``), must **differ** from that of a - :ref:`x509-member-certificate`. - + Distinguished Name (``DN``), must **differ** from the subjects of + :ref:`member x.509 certificates `. + At least one of the Organization (``O``), Organizational Unit (``OU``), or Domain Component (``DC``) attributes in the client certificate must differ from those in the :setting:`net.tls.clusterFile` and - :setting:`net.tls.certificateKeyFile` server certificates. - + :setting:`net.tls.certificateKeyFile` server certificates. If a + client x.509 certificate's subject has the same ``O``, ``OU``, and + ``DC`` combination as the :ref:`x509-member-certificate` (or + :parameter:`tlsX509ClusterAuthDNOverride` if set), the client + connection is rejected. Only :ref:`cluster member x509 certificates + ` should use same ``O``, ``OU``, and + ``DC`` combinations as this grants full permissions. + If the MongoDB deployment has - :parameter:`tlsX509ClusterAuthDNOverride` set (available starting - in MongoDB 4.2), the client x.509 certificate's subject must also + :parameter:`tlsX509ClusterAuthDNOverride` set (*available starting + in MongoDB 4.2*), the client x.509 certificate's subject must also differ from that value. - .. warning:: - - If a client x.509 certificate's subject has the same ``O``, - ``OU``, and ``DC`` combination as the - :ref:`x509-member-certificate` (or - :parameter:`tlsX509ClusterAuthDNOverride` if set), the client - connection is rejected. Only - :ref:`cluster member x509 certificates ` - should use same ``O``, ``OU``, and ``DC`` combinations as this - grants full permissions. + - The x.509 certificate must *not* be expired. - - The x.509 certificate must *not* be expired. - .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst --- ref: x509-certificate-member content: | - The member certificate (:setting:`net.tls.clusterFile`, if - specified, and :setting:`net.tls.certificateKeyFile`), used to - verify membership to the sharded cluster or a replica set, must have - the following properties: + Member certificates which you use to verify membership to a sharded + cluster or a replica set (:setting:`net.tls.clusterFile`, if + specified, and :setting:`net.tls.certificateKeyFile`), must have the + following properties: - A single Certificate Authority (CA) must issue all the x.509 certificates for the members of a sharded cluster or a replica set. - The Distinguished Name (``DN``), found in the member certificate's - ``subject``, must specify a non-empty value for *at least one* of the - following attributes: Organization (``O``), the Organizational Unit - (``OU``) or the Domain Component (``DC``). - + ``subject``, must specify a non-empty value for *at least one* of + the following attributes: + + - the Organization (``O``) + - the Organizational Unit (``OU``) + - the Domain Component (``DC``) + - The Organization attributes (``O``\'s), the Organizational Unit attributes (``OU``\'s), and the Domain Components (``DC``\'s) must match those from both the :setting:`net.tls.clusterFile` and :setting:`net.tls.certificateKeyFile` certificates for the other cluster members (or the :parameter:`tlsX509ClusterAuthDNOverride` value, if set). - + To match, the certificate must match all specifications of these - attributes, or even the non-specification of these attributes. The + attributes, even the non-specification of these attributes. The order of the attributes does not matter. In the following example, the two ``DN``\'s contain matching - specifications for ``O``, ``OU`` as well as the non-specification of - the ``DC`` attribute. + specifications for ``O``, ``OU`` as well as the non-specification + of the ``DC`` attribute. .. code-block:: none @@ -97,8 +95,8 @@ content: | names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names. - For example, the certificates for a cluster could have the following - subjects: + For example, the certificates for a cluster could have the + following subjects: .. code-block:: bash @@ -106,68 +104,49 @@ content: | subject= CN=,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=,OU=Dept1,O=MongoDB,ST=NY,C=US - - *If* the certificate includes the Extended Key Usage (``extendedKeyUsage``) - setting, the value must include ``clientAuth`` ("TLS Web Client - Authentication"). + - *If* the certificate includes the Extended Key Usage + (``extendedKeyUsage``) setting, the value must include + ``clientAuth`` ("TLS Web Client Authentication"). .. code-block:: none extendedKeyUsage = clientAuth - - You can also use a certificate that does not include the Extended - Key Usage (EKU). - - The x.509 certificate must *not* be expired. - + - The x.509 certificate must *not* be expired. + .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst --- ref: x509-member-auth-configuration content: | - In addition to any TLS/SSL configurations as appropriate for your - deployment, include the following to specify x.509 for internal - authentication for each member of your replica set (i.e. the - :binary:`~bin.mongod` instances) or sharded cluster (i.e. the - :binary:`~bin.mongod` and :binary:`~bin.mongos` instances): + You can use TLS for internal authentication between each member of + your replica set (each :binary:`~bin.mongod` instance) or sharded + cluster (each :binary:`~bin.mongod` and :binary:`~bin.mongos` + instance). + + To use TLS for internal authentication, use the following settings: - :setting:`security.clusterAuthMode` or :option:`--clusterAuthMode ` set to ``x509`` - :setting:`net.tls.clusterFile` or :option:`--tlsClusterFile - ` (*both new in MongoDB 4.2*) - - However, if no cluster file is specified, members can use their - certificate key file specified in + ` (*available starting in MongoDB 4.2*) + + :binary:`~bin.mongod` and :option:`mongos ` instances use their certificate key file to + prove their identity to clients, but it can also be used for + membership authentication. If you do not specify a cluster file, + members use their certificate key file for membership authentication. + The certificate key file is the file you specify with :setting:`net.tls.certificateKeyFile` or :option:`--tlsCertificateKeyFile ` - (*both new in MongoDB 4.2*) for membership authentication. This - :setting:`certificate key file ` is used - by :binary:`~bin.mongod` (and :option:`mongos - `) instances to prove their identity - to clients, but can also be used for membership authentication. To - use for both client authentication and membership authentication, - the certificate must either: + (*available starting in MongoDB 4.2*). - - Omit ``extendedKeyUsage`` or + To use the :setting:`certificate key file + ` for both client authentication and + membership authentication, the certificate must either: - - Specify ``extendedKeyUsage`` values - - .. note:: - - Athough still available, :setting:`net.ssl.clusterFile` (and the - correponding :option:`--sslClusterFile `) and :setting:`net.ssl.PEMKeyFile` (and the - corresponding :option:`--sslPEMKeyFile `) - are :ref:`deprecated as of MongoDB 4.2 <4.2-tls>`. - - For deployments using MongoDB version 4.0 and earlier, use - :setting:`net.ssl.clusterFile` (or the corresponding - :option:`--sslClusterFile `) and - :setting:`net.ssl.PEMKeyFile` (or the corresponding - :option:`--sslPEMKeyFile `). - - - The x.509 certificate must *not* be expired. - - .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst + - Omit ``extendedKeyUsage`` or + - Specify ``extendedKeyUsage = serverAuth, clientAuth`` ... diff --git a/source/includes/fact-ssl-certificate-authorities.rst b/source/includes/fact-ssl-certificate-authorities.rst index 904b71469e3..eacaf18f476 100644 --- a/source/includes/fact-ssl-certificate-authorities.rst +++ b/source/includes/fact-ssl-certificate-authorities.rst @@ -1,6 +1,6 @@ For production use, your MongoDB deployment should use valid certificates generated and signed by a certificate authority. You or your organization can generate and maintain an independent certificate -authority, or use certificates generated by third-party TLS/SSL -vendors. Obtaining and managing certificates is beyond the scope of -this documentation. +authority, or use certificates generated by third-party TLS vendors. +Obtaining and managing certificates is beyond the scope of this +documentation. diff --git a/source/includes/list-table-3.0-driver-compatibility.rst b/source/includes/list-table-3.0-driver-compatibility.rst index e3420c82239..71c85c68203 100644 --- a/source/includes/list-table-3.0-driver-compatibility.rst +++ b/source/includes/list-table-3.0-driver-compatibility.rst @@ -9,35 +9,41 @@ * - :driver:`C ` - `1.1.0 `_ - - :driver:`Perl ` - - `1.0.0 `__ + - :driver:`PHP ` + - `1.0 `_ - * - `C++ `_ + * - :driver:`C++ ` - `1.0.0 `__ - - :driver:`PHP ` - - `1.0 `_ + - :driver:`Python ` + - `2.8 `_ * - :driver:`C# ` - `1.10 `_ - - :driver:`Python ` - - `2.8 `_ + - :driver:`Perl ` + - `1.0.0 `__ + + * - :driver:`Go ` + - `1.0.0 `__ + + - :driver:`Ruby ` + - `1.12 `_ * - :driver:`Java ` - `2.13 `_ - - :driver:`Motor ` + - :driver:`Rust ` + - `1.0.0 `__ + + * - :driver:`Motor ` - `0.4 `_ + - :driver:`Scala ` + - `2.8.0 `_ + * - :driver:`Node.js ` - `1.4.29 `_ - - :driver:`Ruby ` - - `1.12 `_ - - * - - - - - - :driver:`Scala ` - - `2.8.0 `_ + - :driver:`Swift ` + - `1.0.0 `__ diff --git a/source/includes/steps-use-x509-authentication.yaml b/source/includes/steps-use-x509-authentication.yaml new file mode 100644 index 00000000000..9086bbeb208 --- /dev/null +++ b/source/includes/steps-use-x509-authentication.yaml @@ -0,0 +1,268 @@ +stepnum: 1 +level: 4 +title: Deploy with x.509 Authentication +stepnum: 2 +level: 4 +ref: deploy-x509 +content: | + + .. _x509-deploy-tls: + + .. tabs:: + + tabs: + + - id: cmdline + name: Command Options + content: | + + You can configure a :binary:`~bin.mongod` instance for x.509 + authentication from the command-line. + + To configure a standalone :binary:`~bin.mongod` instance, run + the following command: + + .. code-block:: bash + + mongod --tlsMode requireTLS \ + --tlsCertificateKeyFile \ + --tlsCAFile --bind_ip + + Include additional options as required for your configuration. + + The x.509 configuration requires: + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :option:`--tlsMode ` + + - Specify ``requireTLS``. + + * - :option:`--tlsCertificateKeyFile ` + + - Specify the instance's x.509 certificate to present to + clients. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify the + certificates presented to the instance. + + - id: cfg + name: Configuration File + content: | + + You can configure a :binary:`~bin.mongod` for x.509 + authentication in the :doc:`configuration file + `. + + To configure a standalone :binary:`~bin.mongod` instance, add + the following configuration options to your configuration + file: + + .. code-block:: yaml + + net: + tls: + mode: requireTLS + certificateKeyFile: + CAFile: + + Include additional options as required for your configuration. + + The x.509 configuration requires: + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :setting:`net.tls.mode` + + - Specify ``requireTLS``. + + * - :setting:`net.tls.certificateKeyFile` + - Specify the instance's x.509 certificate to present to + clients. + + * - :setting:`net.tls.CAFile` + + - Specify the Certificate Authority file to verify the + certificates presented to the instance. + + To set up x.509 authentication for replica sets or sharded clusters, + see :ref:`x509-internal-authentication`. + +--- +title: Add x.509 Certificate ``subject`` as a User +stepnum: 2 +level: 4 +ref: x509-add-user +content: | + + .. _addX509SubjectUser: + + To authenticate with a client certificate, you must first add the value + of the ``subject`` from the client certificate as a MongoDB user to the + ``$external`` database. Each 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. + + .. note:: Username Requirements + + - .. include:: /includes/extracts/sessions-external-username-limit.rst + + - The RDNs in the ``subject`` string must be compatible with the + `RFC2253 `_ standard. + + #. You can retrieve the ``RFC2253`` formatted ``subject`` from the + client certificate with the following command: + + .. code-block:: bash + + openssl x509 -in -inform PEM -subject -nameopt RFC2253 + + The command returns the ``subject`` string and the certificate: + + .. code-block:: bash + + subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry + -----BEGIN CERTIFICATE----- + # ... + -----END CERTIFICATE----- + + + #. Add the ``RFC2253`` compliant value of the ``subject`` as a user. + Omit spaces as needed. + + The following example adds a user and grants the user + :authrole:`readWrite` role in the ``test`` database and the + :authrole:`userAdminAnyDatabase` role: + + .. code-block:: javascript + + db.getSiblingDB("$external").runCommand( + { + createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry", + roles: [ + { role: "readWrite", db: "test" }, + { role: "userAdminAnyDatabase", db: "admin" } + ], + writeConcern: { w: "majority" , wtimeout: 5000 } + } + ) + + See :doc:`/tutorial/manage-users-and-roles` for details on adding a user + with roles. +--- +title: Authenticate with a x.509 Certificate +stepnum: 3 +level: 4 +ref: x509-authenticate +content: | + + .. _authenticate-with-x509-cert: + + After you have :ref:`added the x.509 client certificate subject as a + corresponding MongoDB user `, you can + authenticate with the client certificate: + + .. tabs:: + + tabs: + + - id: connect + name: Connect with Authentication + content: | + + To authenticate during connection, run the following command: + + .. code-block:: bash + + mongosh --tls --tlsCertificateKeyFile \ + --tlsCAFile \ + --authenticationDatabase '$external' \ + --authenticationMechanism MONGODB-X509 + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Option + - Notes + + * - :option:`--tls ` + - + + * - :option:`--tlsCertificateKeyFile ` + - Specify the client's x.509 file. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify the + certificate presented by the :binary:`~bin.mongod` + instance. + + * - :option:`--authenticationDatabase ` + - Specify ``'$external'``. + + * - :option:`--authenticationMechanism ` + - Specify ``MONGODB-X509``. + + - id: authafter + name: Authenticate after Connection + content: | + + You can connect without authentication and use the + :method:`db.auth()` method to authenticate after + connection. + + For example, if using :binary:`~bin.mongosh`, + + 1. Connect :binary:`~bin.mongosh` to the + :binary:`~bin.mongod`: + + .. code-block:: bash + + mongosh --tls --tlsCertificateKeyFile \ + --tlsCAFile + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :option:`--tls ` + - + + * - :option:`--tlsCertificateKeyFile ` + - Specify the client's x.509 file. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify + the certificate presented by the + :binary:`~bin.mongod` or :binary:`~bin.mongos` + instance. + + #. To authenticate, use the :method:`db.auth()` method in + the ``$external`` database. For the ``mechanism`` field, + specify ``"MONGODB-X509"``. + + .. code-block:: javascript + + db.getSiblingDB("$external").auth( + { + mechanism: "MONGODB-X509" + } + ) +... diff --git a/source/tutorial/configure-scram-client-authentication.txt b/source/tutorial/configure-scram-client-authentication.txt new file mode 100644 index 00000000000..b77ad4702a4 --- /dev/null +++ b/source/tutorial/configure-scram-client-authentication.txt @@ -0,0 +1,32 @@ +.. _scram-client-authentication: + +================================= +Use SCRAM to Authenticate Clients +================================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +The following procedure sets up SCRAM for client authentication on a +standalone :binary:`~bin.mongod` instance. + +To use SCRAM authentication for replica sets or sharded clusters, see +:doc:`/tutorial/deploy-replica-set-with-keyfile-access-control`. + +.. _enable-auth-procedure: + +Procedure +--------- + +.. include:: /includes/steps/create-admin-then-enable-authentication.rst + +Next Steps +---------- + +To use SCRAM authentication for replica sets or sharded clusters, see +:doc:`/tutorial/deploy-replica-set-with-keyfile-access-control`. diff --git a/source/tutorial/configure-x509-client-authentication.txt b/source/tutorial/configure-x509-client-authentication.txt index 2ea6152a09f..a50d75ad2fc 100644 --- a/source/tutorial/configure-x509-client-authentication.txt +++ b/source/tutorial/configure-x509-client-authentication.txt @@ -1,4 +1,4 @@ -.. _ x509-client-authentication: +.. _x509-client-authentication: ============================================== Use x.509 Certificates to Authenticate Clients @@ -12,18 +12,9 @@ Use x.509 Certificates to Authenticate Clients :depth: 1 :class: singlecol -.. |binary| replace:: MongoDB - -.. note:: - - .. include:: /includes/fact-tls-1.0.rst -MongoDB supports x.509 certificate authentication for use with a secure -:doc:`TLS/SSL connection `. The x.509 client -authentication allows :ref:`clients to authenticate to servers with -certificates ` rather than with a username -and password. The following tutorial outlines the steps to use x.509 -for client authentication with a standalone :binary:`~bin.mongod` instance. +The following procedure sets up x.509 certificate authentication for +client authentication on a standalone :binary:`~bin.mongod` instance. To use x.509 authentication for replica sets or sharded clusters, see :doc:`/tutorial/configure-x509-member-authentication`. @@ -31,9 +22,7 @@ To use x.509 authentication for replica sets or sharded clusters, see Prerequisites ------------- -.. important:: - - .. include:: /includes/extracts/security-prereq-configure-x509-client-authentication.rst +.. include:: /includes/extracts/security-prereq-configure-x509-client-authentication.rst Certificate Authority @@ -41,492 +30,25 @@ Certificate Authority .. include:: /includes/fact-ssl-certificate-authorities.rst -.. important:: - - .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst +.. include:: /includes/extracts/ssl-facts-x509-ca-file.rst -.. _x509-client-authentication: Client x.509 Certificate ~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - You must have valid x.509 certificates. - - .. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst - -.. include:: /includes/extracts/x509-certificate-client.rst - -.. _x509-deploy-tls: - -MongoDB Deployment Configured for x.509 (Using TLS Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``tls`` settings/option - (Available in MongoDB 4.2). For procedures using their ``ssl`` - aliases, see :ref:`x509-deploy-ssl`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -.. tabs:: - - tabs: - - - id: cmdline - name: Command-Options - content: | - - You can configure a :binary:`~bin.mongod` instance - for x.509 authentication from the command-line. For example, - to configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: bash - - mongod --tlsMode requireTLS --tlsCertificateKeyFile --tlsCAFile --bind_ip - - .. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst - - The x.509 configuration requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :option:`--tlsMode ` - - - Specify ``requireTLS``. - - * - :option:`--tlsCertificateKeyFile ` - - The instance's x.509 certificate to present to clients. - - * - :option:`--tlsCAFile ` - - - Certificate Authority file to verify the certificates - presented to the instance. - - - id: cfg - name: Configuration File - content: | - - You can configure :binary:`~bin.mongod` for x.509 - authentication in the :doc:`configuration file - `. For example, to - configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: yaml - - net: - tls: - mode: requireTLS - certificateKeyFile: - CAFile: - - .. include:: /includes/extracts/default-bind-ip-security-additional-config-file.rst - - The x.509 configuration requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :setting:`net.tls.mode` - - - Specify ``requireTLS``. - - * - :setting:`net.tls.certificateKeyFile` - - The instance's x.509 certificate. - - * - :setting:`net.tls.CAFile` - - - Certificate Authority file to verify the certificates - presented to the instance. +You must have valid x.509 certificates. The client x.509 certificates +must meet the :ref:`client certificate requirements +`. -To set up x.509 authentication for replica sets or sharded clusters, -see :doc:`configure-x509-member-authentication`. +.. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst +Procedure +--------- -.. _x509-deploy-ssl: +.. include:: /includes/steps/use-x509-authentication.rst -MongoDB Deployment Configured for x.509 (Using SSL Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``ssl`` settings/option. For - procedures using their ``tls`` aliases (Available in MongoDB 4.2), - see :ref:`x509-deploy-tls`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -.. tabs:: - - tabs: - - - id: cmdline - name: Command-Options - content: | - - You can configure a :binary:`~bin.mongod` instance - for x.509 authentication from the command-line. For example, - to configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: bash - - mongod --sslMode requireSSL --sslPEMKeyFile --sslCAFile --bind_ip - - .. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst - - The x.509 configuration for a standalone requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :option:`--sslMode ` - - - Specify ``requireSSL``. - - * - :option:`--sslPEMKeyFile ` - - The instance's x.509 certificate. - - * - :option:`--sslCAFile ` - - - Certificate Authority file to verify the certificate - presented to the instance. - - - id: cfg - name: Configuration File - content: | - - You can configure :binary:`~bin.mongod` - for x.509 authentication in the :doc:`configuration file - `. For example, - to configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: yaml - - net: - ssl: - mode: requireSSL - PEMKeyFile: - CAFile: - - .. include:: /includes/extracts/default-bind-ip-security-additional-config-file.rst - - The x.509 configuration for a standalone requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :setting:`net.ssl.mode` - - - Specify ``requireSSL``. - - * - :setting:`net.ssl.PEMKeyFile` - - The instance's x.509 certificate. - - * - :setting:`net.ssl.CAFile` - - - Certificate Authority file to verify the certificate - presented to the instance. - -To set up x.509 authentication for replica sets or sharded clusters, -see :doc:`configure-x509-member-authentication`. - -Procedures +Next Steps ---------- -.. _addX509SubjectUser: - -Add x.509 Certificate ``subject`` as a User -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To authenticate with a client certificate, you must first add the value -of the ``subject`` from the client certificate as a MongoDB user to the -``$external`` database. 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. - -.. include:: /includes/extracts/sessions-external-username-limit.rst - -.. note:: - - The RDNs in the ``subject`` string must be compatible with the - `RFC2253 `_ standard. - -#. You can retrieve the ``RFC2253`` formatted ``subject`` from the client - certificate with the following command: - - .. code-block:: bash - - openssl x509 -in -inform PEM -subject -nameopt RFC2253 - - The command returns the ``subject`` string as well as certificate: - - .. code-block:: bash - - subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry - -----BEGIN CERTIFICATE----- - # ... - -----END CERTIFICATE----- - - - -#. Add the ``RFC2253`` compliant value of the ``subject`` as a user. - Omit spaces as needed. - - For example, the following adds a user and grants the user - :authrole:`readWrite` role in the ``test`` database and the - :authrole:`userAdminAnyDatabase` role: - - .. code-block:: javascript - - db.getSiblingDB("$external").runCommand( - { - createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry", - roles: [ - { role: "readWrite", db: "test" }, - { role: "userAdminAnyDatabase", db: "admin" } - ], - writeConcern: { w: "majority" , wtimeout: 5000 } - } - ) - -See :doc:`/tutorial/manage-users-and-roles` for details on adding a user -with roles. - -.. _authenticate-with-x509-cert: - -Authenticate with a x.509 Certificate (Using ``tls`` Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``tls`` settings/option - (Available in MongoDB 4.2). For procedures using their ``ssl`` - aliases, see :ref:`authenticate-with-x509-cert-ssl`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -After you have :ref:`added the x.509 client certificate subject as a -corresponding MongoDB user `, you can -authenticate with the client certificate. - -.. tabs:: - - tabs: - - - id: connect - name: Connect with Authentication - content: | - - To authenticate during connection: - - .. code-block:: bash - - mongosh --tls --tlsCertificateKeyFile --tlsCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 - - .. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Option - - Notes - - * - :option:`--tls ` - - - - * - :option:`--tlsCertificateKeyFile ` - - Client's x.509 file. - - * - :option:`--tlsCAFile ` - - - Certificate Authority file to verify the - certificate presented by the - :binary:`~bin.mongod` - instance. - - * - :option:`--authenticationDatabase ` - - Specify ``'$external'``. - - * - :option:`--authenticationMechanism ` - - Specify ``MONGODB-X509``. - - - id: authafter - name: Authenticate after Connection - content: | - - You can connect without authentication and use the - :method:`db.auth()` method to authenticate after - connection. - - For example, if using :binary:`~bin.mongosh`, - - 1. Connect :binary:`~bin.mongosh` to the :binary:`~bin.mongod` set up for - TLS/SSL: - - .. code-block:: bash - - mongosh --tls --tlsCertificateKeyFile --tlsCAFile - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :option:`--tls ` - - - - * - :option:`--tlsCertificateKeyFile ` - - Client's x.509 file. - - * - :option:`--tlsCAFile ` - - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. - - #. To perform the authentication, use the :method:`db.auth()` method in - the ``$external`` database. For the ``mechanism`` - field, specify ``"MONGODB-X509"``. - - .. code-block:: javascript - - db.getSiblingDB("$external").auth( - { - mechanism: "MONGODB-X509" - } - ) - -.. _authenticate-with-x509-cert-ssl: - -Authenticate with a x.509 Certificate (Using ``ssl`` Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``ssl`` settings/options. For - procedures using their ``tls`` (Available in MongoDB 4.2) aliases, - see :ref:`authenticate-with-x509-cert`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -After you have :ref:`added the x.509 client certificate subject as a -corresponding MongoDB user `, you can -authenticate with the client certificate. - -.. tabs:: - - tabs: - - - id: connect - name: Connect with Authentication - content: | - - To authenticate during connection: - - .. code-block:: bash - - mongosh --ssl --sslPEMKeyFile --sslCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 - - .. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Option - - Notes - - * - ``--ssl`` - - - - * - ``--sslPEMKeyFile`` - - Client's x.509 file. - - * - ``--sslCAFile`` - - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. - - * - :option:`--authenticationDatabase ` - - Specify ``'$external'``. - - * - :option:`--authenticationMechanism ` - - Specify ``MONGODB-X509``. - - - id: authafter - name: Authenticate after Connection - content: | - - You can connect without authentication and use the - :method:`db.auth()` method to authenticate after - connection. - - For example, if using :binary:`~bin.mongosh`, - - 1. Connect :binary:`~bin.mongosh` to the :binary:`~bin.mongod` set up for - TLS/SSL: - - .. code-block:: bash - - mongosh --ssl --sslPEMKeyFile --sslCAFile - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - ``--ssl`` - - - - * - ``--sslPEMKeyFile`` - - Client's x.509 file. - - * - ``--sslCAFile`` - - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. - - #. To perform the authentication, use the :method:`db.auth()` method in - the ``$external`` database. For the ``mechanism`` - field, specify ``"MONGODB-X509"``. - - .. code-block:: javascript - - db.getSiblingDB("$external").auth( - { - mechanism: "MONGODB-X509" - } - ) +To use x.509 authentication for replica sets or sharded clusters, see +:doc:`/tutorial/configure-x509-member-authentication`. diff --git a/source/tutorial/enable-authentication.txt b/source/tutorial/enable-authentication.txt index e1b96235d36..99da6affbaf 100644 --- a/source/tutorial/enable-authentication.txt +++ b/source/tutorial/enable-authentication.txt @@ -17,11 +17,17 @@ With access control enabled, users are required to identify themselves and can only perform actions that adhere to the permissions granted by the roles assigned to their user. -The following tutorial enables access control for a standalone -:binary:`~bin.mongod` instance and uses the :ref:`default -authentication mechanism `. For more -information about other authentication mechanisms, see -:ref:`available-authentication-mechanisms`. +If you would like to enable access control for a standalone MongoDB +instance, please refer to one of the following resources: + +- :doc:`/tutorial/configure-scram-client-authentication` +- :doc:`/tutorial/configure-x509-client-authentication` +- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` +- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` +- :doc:`/tutorial/kerberos-auth-activedirectory-authz` +- :doc:`/tutorial/configure-ldap-sasl-activedirectory` +- :doc:`/tutorial/configure-ldap-sasl-openldap` +- :doc:`/tutorial/authenticate-nativeldap-activedirectory` If you would like to enable access control for a :doc:`replica set ` or a :doc:`sharded cluster `, please refer to @@ -33,17 +39,12 @@ one of the following resources: - :doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control` - :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster` - :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime` - -.. _enable-auth-procedure: - -Enable Access Control for a Standalone ``mongod`` Instance ----------------------------------------------------------- - -.. seealso:: - - :ref:`available-authentication-mechanisms` - -.. include:: /includes/steps/create-admin-then-enable-authentication.rst +- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` +- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` +- :doc:`/tutorial/kerberos-auth-activedirectory-authz` +- :doc:`/tutorial/configure-ldap-sasl-activedirectory` +- :doc:`/tutorial/configure-ldap-sasl-openldap` +- :doc:`/tutorial/authenticate-nativeldap-activedirectory` Next Steps ----------