Skip to content

DOCS-3701-3736-3834 #1942

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

DOCS-3701-3736-3834 #1942

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions source/tutorial/configure-x509-client-authentication.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Use x.509 Certificates to Authenticate Clients
MongoDB supports x.509 certificate authentication for use with a secure
:doc:`SSL connection </tutorial/configure-ssl>`. The x.509 client
authentication allows :ref:`clients to authenticate to servers with
certificates <x509-client-authentication>` instead of with username and
certificates <x509-client-authentication>` rather than with a username and
password.

To use x.509 authentication for the internal authentication of replica
Expand Down Expand Up @@ -37,7 +37,7 @@ properties:
keyUsage = digitalSignature
extendedKeyUsage = clientAuth

- Client x.509 certificate’s subject, which contains the Distinguished
- A client x.509 certificate’s subject, which contains the Distinguished
Name (``DN``), must differ from that of a
:ref:`x509-member-certificate` to prevent client certificates from
identifying the client as a cluster member and granting full
Expand All @@ -54,21 +54,31 @@ Configure MongoDB Server
Use Command-line Options
~~~~~~~~~~~~~~~~~~~~~~~~

Configure the MongoDB server from the command line, as in the following:
You can configure the MongoDB server from the command line, e.g.:

.. code-block:: sh

mongod --sslMode requireSSL --sslPEMKeyFile <path to SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>

.. warning::

For security reasons, if the :setting:`--sslCAFile` option and its target
file are not specified, x.509 client authentication will not function.
:program:`mongod` will not be able to verify the client's certificate
against the trusted certificate authority (CA) that issued it, breaking the
certificate chain.

As of version 2.6.4, :program:`mongod` will not start with x.509
authentication enabled if the CA file is not specified.

Use Configuration File
~~~~~~~~~~~~~~~~~~~~~~

You may also specify these options in the :doc:`configuration file
</reference/configuration-options>`.

Starting in MongoDB 2.6, you can specify the configuration for MongoDB
in a :doc:`YAML format </reference/configuration-options>`, as in the
following example:
in :doc:`YAML format </reference/configuration-options>`, e.g.:

.. code-block:: yaml

Expand All @@ -79,8 +89,8 @@ following example:
CAFile: <path to root CA PEM file>

For backwards compatibility, you can also specify the configuration
using the :v2.4:`older configuration file format
</reference/configuration>`, as in the following example:
using the :v2.4:`older configuration file format </reference/configuration>`,
e.g.:

.. code-block:: none

Expand Down Expand Up @@ -173,7 +183,7 @@ For example, if using the :program:`mongo` shell,

.. code-block:: sh

mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file>
mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>

#. To perform the authentication, use the :method:`db.auth()` method in
the ``$external`` database. For the ``mechanism`` field, specify
Expand Down
22 changes: 21 additions & 1 deletion source/tutorial/configure-x509-member-authentication.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,14 @@ following properties:
subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US
subject= CN=<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US

It is possible to use a single x509 certificate for both member
authentication and :doc:`x.509 client authentication </tutorial/configure-x509-client-authentication>`.
To do so, obtain a certificate with both ``clientAuth`` and ``serverAuth``
(i.e. "TLS Web Client Authentication" and "TLS Web Server Authentication")
specified as Extended Key Usage (EKU) values, or simply do not specify any EKU
values. Provide this file as the the :option:`--sslPEMKeyFile
<mongod --sslPEMKeyFile>` and omit the :option:`--sslClusterFile
<mongod --sslClusterFile>` option described below.

Configure Replica Set/Sharded Cluster
-------------------------------------
Expand All @@ -99,6 +107,18 @@ encrypted, set the :option:`--sslClusterPassword` to the passphrase to
decrypt the key or have MongoDB prompt for the passphrase. See
:ref:`ssl-certificate-password` for details.

.. warning::

For security reasons, if the :setting:`--sslCAFile` option and its target
file are not specified, x.509 member authentication will not function. Any
:program:`mongod` or :program:`mongos` without this option set
will not be able to verify any other server process' certificate against the
trusted certificate authority (CA) that issued it, breaking the
certificate chain.

As of version 2.6.4, :program:`mongod` and :program:`mongos` will not
start with x.509 authentication enabled if the CA file is not specified.

Use Configuration File
~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -109,7 +129,7 @@ YAML Formatted Configuration File
`````````````````````````````````

Starting in MongoDB 2.6, you can specify the configuration for MongoDB
in a :doc:`YAML format </reference/configuration-options>`, as in the
in :doc:`YAML format </reference/configuration-options>`, as in the
following example:

.. code-block:: yaml
Expand Down