Configure mongod and mongos for TLS/SSL (original) (raw)

This document helps you to configure a new MongoDB instance to support TLS/SSL. For instructions on upgrading a cluster currently not using TLS/SSL to using TLS/SSL, see Upgrade a Cluster to Use TLS/SSLinstead.

MongoDB uses the native TLS/SSL OS libraries:

Note

• MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available.
• MongoDB's TLS/SSL encryption only allows the use of strong TLS/SSL ciphers with a minimum of 128-bit key length for all connections.
• The Linux 64-bit legacy x64 builds of MongoDB do not include support for TLS/SSL.

Important

A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authority is beyond the scope of this document. This page assumes prior knowledge of TLS/SSL as well as access to valid certificates.

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 vendors. Obtaining and managing certificates is beyond the scope of this documentation.

When TLS is enabled, use member certificates to verify membership to internal connections in a sharded cluster or a replica set. You can configure member certificate file paths with thenet.tls.clusterFile and net.tls.certificateKeyFileoptions. Members have the following configuration requirements:

• Cluster member configuration must specify a non-empty value for at least one of the attributes used for authentication. By default, MongoDB accepts:
  • the Organization (O)
  • the Organizational Unit (OU)
  • the Domain Component (DC)
    You can specify alternative attributes to use for authentication by setting net.tls.clusterAuthX509.extensionValue.
• Cluster member configuration must include the samenet.tls.clusterAuthX509.attributes and use matching values. Attribute order doesn't matter. The following example sets O andOU, but not DC:

net:  
  tls:  
    clusterAuthX509:  
      attributes: O=MongoDB, OU=MongoDB Server  

Note

If you disable the enforceUserClusterSeparation parameter, the following behaviors apply:

• The O/OU/DC check is disabled if clusterAuthMode iskeyFile in your configuration file. This allows clients possessing member certificates to authenticate as users stored in the $external database.
• The server won't start if clusterAuthMode isn't keyFile in your configuration file.

If you set the enforceUserClusterSeparation parameter to false, the server doesn't distinguish between client certificates, which applications use to authenticate, and intra-cluster certificates, which have privileged access. This has no effect if your clusterAuthModeis keyFile. However, if your clusterAuthMode is x509, user certificates that use the allowed scheme are conflated with cluster certificates and granted privileged access.

Your existing certificates are granted internal privileges if you do the following:

1. Create a user, with a name allowed by this parameter.
2. Set the enforceUserClusterSeparation parameter to false.
3. Set clusterAuthMode to x509.

You must not upgrade from keyFile to x509 without validating that you've removed users with elevated privileges that theenforceUserClusterSeparation flag allowed you to create.

To set the enforceUserClusterSeparation parameter tofalse, run the following command during startup:

mongod --setParameter enforceUserClusterSeparation=false

The certificates have the following requirements:

• A single Certificate Authority (CA) must issue all X.509 certificates for the members of a sharded cluster or a replica set.
• At least one of the Subject Alternative Name (SAN) entries must match the server hostname used by other cluster members. When comparing SANs, MongoDB can compare either DNS names or IP addresses.
  If you don't specify subjectAltName, MongoDB compares the Common Name (CN) instead. However, this usage of CN is deprecated per RFC2818
• If the certificate used as the certificateKeyFile includesextendedKeyUsage, the value must include bothclientAuth ("TLS Web Client Authentication") and serverAuth("TLS Web Server Authentication").

extendedKeyUsage = clientAuth, serverAuth  

• If the certificate used as the clusterFile includesextendedKeyUsage, the value must include clientAuth.

extendedKeyUsage = clientAuth  

When establishing a TLS/SSL connection, themongod / mongos presents a certificate key file to its clients to establish its identity. [1] The certificate key file contains a public key certificate and its associated private key, but only the public component is revealed to the client.

MongoDB can use any valid TLS/SSL certificate issued by a certificate authority, or a self-signed certificate. If you use a self-signed certificate, although the communications channel will be encrypted to prevent eavesdropping on the connection, there will be no validation of server identity. This leaves you vulnerable to a man-in-the-middle attack. Using a certificate signed by a trusted certificate authority will permit MongoDB drivers to verify the server's identity.

In general, avoid using self-signed certificates unless the network is trusted.

With regards to certificates for replica set and sharded cluster members, it is advisable to use different certificates on different servers. This minimizes exposure of the private key and allows for hostname validation.

Note

If a MongoDB deployment is not configured to use a CA file, it bypasses client certificate validation.

Note

MongoDB provides net.tls settings (and --tls command-line options) that correspond to the net.ssl settings (and --ssl command-line options). The new tls settings provide identical functionality as the sslsettings since MongoDB has always supported TLS 1.0 and later.

The procedures in this section use the net.tls settings. For procedures using the net.ssl alias, see Procedures (Using net.ssl Settings).

The following section configuresmongod / mongos to use TLS/SSL connections. With these TLS/SSL settings,mongod / mongos presents its certificate key file to the client. However, themongod / mongos does not require a certificate key file from the client to verify the client's identity. To require client's certificate key file, seeSet Up mongod and mongos with Client Certificate Validation instead.

Note

The procedure uses the net.tls settings. For procedures that use thenet.ssl settings, see Procedures (Using net.ssl Settings).

To use TLS/SSL connections, include the following TLS/SSL settings in yourmongod / mongos instance'sconfiguration file:

For example, consider the following configuration file for a mongod instance:

net:

   tls:

      mode: requireTLS

      certificateKeyFile: /etc/ssl/mongodb.pem

systemLog:

   destination: file

   path: "/var/log/mongodb/mongod.log"

   logAppend: true

storage:

   dbPath: "/var/lib/mongodb"

processManagement:

   fork: true

net:

   bindIp: localhost,mongodb0.example.net

   port: 27017

You can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specifynet.tls.certificateSelector instead of specifying the certificate key file.

For example, consider the following configuration file for a mongod instance:

net:

   tls:

      mode: requireTLS

      certificateSelector: subject="<CertificateCommonName>"

systemLog:

   destination: file

   path: "/var/log/mongodb/mongod.log"

   logAppend: true

storage:

   dbPath: "/var/lib/mongodb"

processManagement:

   fork: true

net:

   bindIp: localhost,mongodb0.example.net

   port: 27017

A mongod instance that uses the above configuration can only accept TLS/SSL connections:

mongod --config <path/to/configuration/file>

See Connect to MongoDB Instances Using Encryption for more information on connecting with TLS/SSL.

See also:

The following section configuresmongod / mongos to use TLS/SSL connections and perform client certificate validation. With these TLS/SSL settings:

• mongod / mongos presents its certificate key file to the client for verification.
• mongod / mongos requires a certificate key file from the client to verify the client's identity.

Note

The procedure uses the net.tls settings For procedures that use thenet.ssl settings, see Procedures (Using net.ssl Settings).

To use TLS/SSL connections and perform client certificate validation, include the following TLS/SSL settings in your mongod / mongos instance'sconfiguration file:

Note

You can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specify net.ssl.certificateSelector instead of specifying the certificate key file.

Important

When starting a mongod instance withTLS/SSL enabled, you must specify a value for the --tlsCAFile flag, thenet.tls.CAFile configuration option, or the tlsUseSystemCAparameter.

--tlsCAFile, tls.CAFile, and tlsUseSystemCA are all mutually exclusive.

For example, consider the following configuration file for a mongod instance:

net:

   tls:

      mode: requireTLS

      certificateKeyFile: /etc/ssl/mongodb.pem

      CAFile: /etc/ssl/caToValidateClientCertificates.pem

systemLog:

   destination: file

   path: "/var/log/mongodb/mongod.log"

   logAppend: true

storage:

   dbPath: "/var/lib/mongodb"

processManagement:

   fork: true

net:

   bindIp: localhost,mongodb0.example.net

   port: 27017

A mongod instance that uses the above configuration can only accept TLS/SSL connections and requires a valid certificate from its clients:

mongod --config <path/to/configuration/file>

Clients must specify TLS/SSL connections and present their certificate key file to the instance. SeeConnect to MongoDB Instances that Require Client Certificates for more information on connecting with TLS/SSL.

See also:

Note

The procedure uses the net.tls settings. For procedures that use thenet.ssl settings, see Procedures (Using net.ssl Settings).

To prevent clients with revoked certificates from connecting to themongod or mongos instance, you can use a Certificate Revocation List (CRL).

To specify a CRL file, includenet.tls.CRLFile set to a file that contains revoked certificates.

For example:

net:

   tls:

      mode: requireTLS

      certificateKeyFile: /etc/ssl/mongodb.pem

      CAFile: /etc/ssl/caToValidateClientCertificates.pem

      CRLFile: /etc/ssl/revokedCertificates.pem

Clients that present certificates that are listed in the/etc/ssl/revokedCertificates.pem file are not able to connect.

See also:

In most cases, it is important to ensure that clients present valid certificates. However, if you have clients that cannot present a client certificate or are transitioning to using a certificate, you may only want to validate certificates from clients that present a certificate.

Note

The procedure uses the net.tls settings. For procedures using thenet.ssl settings, see Procedures (Using net.ssl Settings).

To bypass client certificate validation for clients that do not present a certificate, includenet.tls.allowConnectionsWithoutCertificates set to true.

For example:

net:

  tls:

    mode: requireTLS

    certificateKeyFile: /etc/ssl/mongodb.pem

    CAFile: /etc/ssl/caToValidateClientCertificates.pem

    allowConnectionsWithoutCertificates: true

A mongod / mongos running with these settings allows connection from:

• Clients that do not present a certificate.
• Clients that present a valid certificate.

Note

If the client presents a certificate, the certificate must be a valid certificate.

All connections, including those that have not presented certificates, are encrypted using TLS/SSL.

See TLS/SSL Configuration for Clients for more information on TLS/SSL connections for clients.

See also:

Note

The procedure uses the net.tls settings. For procedures using thenet.ssl settings, see Procedures (Using net.ssl Settings).

To prevent MongoDB servers from accepting incoming connections that use specific protocols, include net.tls.disabledProtocols set to the disallowed protocols.

For example, the following configuration preventsmongod / mongos from accepting incoming connections that use either TLS1_0 or TLS1_1

net:

  tls:

    mode: requireTLS

    certificateKeyFile: /etc/ssl/mongodb.pem

    CAFile: /etc/ssl/caToValidateClientCertificates.pem

    disabledProtocols: TLS1_0,TLS1_1

See also:

If the certificate key files formongod / mongos are encrypted, includenet.tls.certificateKeyFilePassword set to the passphrase.

Tip

To avoid specifying the passphrase in cleartext, you can use anexpansion value in the configuration file.

See also:

Starting in MongoDB 5.0, you can rotate the following certificate key files on-demand:

• TLS Certificates
• CRL (Certificate Revocation List) files(on Linux and Windows platforms)
• CA (Certificate Authority) files

To rotate one or more of these certificates:

1. Replace the certificate or certificates you wish to rotate on the filesystem, noting the following constraints:
   • Each new certificate must have the same filename and_same filepath_ as the certificate it is replacing.
   • If rotating an encrypted TLS Certificate, its password must be the same as the password for the old certificate (as specified to thecertificateKeyFilePassword configuration file setting). Certificate rotation does not support the interactive password prompt.
2. Connect mongosh to the mongod ormongos instance that you wish to perform certificate rotation on.
3. Run the rotateCertificates command or thedb.rotateCertificates() shell method to rotate the certificates used by the mongod ormongos instance.

When certificate rotation takes place:

• Existing connections to the mongod ormongos instance are not terminated, and will continue to use the old certificates.
• Any new connections will use the new certificates.

Incorrect, expired, revoked, or missing certificate files will cause the certificate rotation to fail, but will not invalidate the existing TLS configuration or terminate the running mongod ormongos process.

Previous to MongoDB 5.0, certificate rotation required downtime, and was typically performed during maintenance windows.

See rotateCertificates or db.rotateCertificates()for additional considerations and full usage instructions.

Note

See Configure MongoDB for FIPS for more details.

To configure TLS/SSL support for clients, seeTLS/SSL Configuration for Clients.

See also:

Note

MongoDB provides net.tls settings (and --tls command-line options) that correspond to the net.ssl settings (and --ssl command-line options). The new tls settings provide identical functionality as the sslsettings since MongoDB has always supported TLS 1.0 and later.

The procedures in this section use the net.ssl settings. For procedures using the net.tls aliases, see Procedures (Using net.tls Settings).

The following section configuresmongod / mongos to use TLS/SSL connections. With these TLS/SSL settings,mongod / mongos presents its certificate key file to the client. However, themongod / mongos does not require a certificate key file from the client to verify the client's identity. To require client's certificate key file, seeSet Up mongod and mongos with Client Certificate Validation instead.

To use TLS/SSL connections, include the following TLS/SSL settings in your mongod / mongos instance'sconfiguration file:

For example, consider the following configuration file for a mongod instance:

net:

   ssl:

      mode: requireSSL

      PEMKeyFile: /etc/ssl/mongodb.pem

systemLog:

   destination: file

   path: "/var/log/mongodb/mongod.log"

   logAppend: true

storage:

   dbPath: "/var/lib/mongodb"

processManagement:

   fork: true

net:

   bindIp: localhost,mongodb0.example.net

   port: 27017

You can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specifynet.ssl.certificateSelector instead of specifying the certificate key file.

For example, consider the following configuration file for a mongod instance:

net:

   ssl:

      mode: requireSSL

      certificateSelector: subject="<CertificateCommonName>"

systemLog:

   destination: file

   path: "/var/log/mongodb/mongod.log"

   logAppend: true

storage:

   dbPath: "/var/lib/mongodb"

processManagement:

   fork: true

net:

   bindIp: localhost,mongodb0.example.net

   port: 27017

A mongod instance that uses the above configuration can only accept TLS/SSL connections:

mongod --config <path/to/configuration/file>

See Connect to MongoDB Instances Using Encryption for more information on connecting with TLS/SSL.

See also:

You can also configure mongod and mongosusing command-line options instead of the configuration file:

• For mongod, see --sslMode, --sslPEMKeyFile, and --sslCertificateSelector.
• For mongos, see: --sslMode,--sslPEMKeyFile and --sslCertificateSelector.

The following section configuresmongod / mongos to use TLS/SSL connections and perform client certificate validation. With these TLS/SSL settings:

• mongod / mongos presents its certificate key file to the client for verification.
• mongod / mongos requires a certificate key file from the client to verify the client's identity.

To use TLS/SSL connections, include the following TLS/SSL settings in your mongod / mongos instance'sconfiguration file:

Note

You can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specify net.ssl.certificateSelector instead of specifying the certificate key file.

For example, consider the following configuration file for a mongod instance:

net:

   ssl:

      mode: requireSSL

      PEMKeyFile: /etc/ssl/mongodb.pem

      CAFile: /etc/ssl/caToValidateClientCertificates.pem

systemLog:

   destination: file

   path: "/var/log/mongodb/mongod.log"

   logAppend: true

storage:

   dbPath: "/var/lib/mongodb"

processManagement:

   fork: true

net:

   bindIp: localhost,mongodb0.example.net

   port: 27017

A mongod instance that uses the above configuration can only accept TLS/SSL connections and requires a valid certificate from its clients:

mongod --config <path/to/configuration/file>

Clients must specify TLS/SSL connections and present their certificate key file to the instance. SeeConnect to MongoDB Instances that Require Client Certificates for more information on connecting with TLS/SSL.

See also:

You can also configure mongod andmongos using command-line options instead of the configuration file:

• For mongod, see --sslMode, --sslPEMKeyFile, and--sslCAFile.
• For mongos, see --sslMode, --sslPEMKeyFile, and--sslCAFile.

To prevent clients with revoked certificates from connecting to themongod or mongos instance, you can use a Certificate Revocation List (CRL).

To specify a CRL file, includenet.ssl.CRLFile set to a file that contains revoked certificates.

For example:

net:

   ssl:

      mode: requireSSL

      PEMKeyFile: /etc/ssl/mongodb.pem

      CAFile: /etc/ssl/caToValidateClientCertificates.pem

      CRLFile: /etc/ssl/revokedCertificates.pem

Clients that present certificates that are listed in the/etc/ssl/revokedCertificates.pem file are not able to connect.

See also:

You can also configure the revoked certificate list using the command-line option.

• For mongod, see --sslCRLFile.
• For mongos, see --sslCRLFile.

In most cases, it is important to ensure that clients present valid certificates. However, if you have clients that cannot present a client certificate or are transitioning to using a certificate, you may only want to validate certificates from clients that present a certificate.

To bypass client certificate validation for clients that do not present a certificate, includenet.ssl.allowConnectionsWithoutCertificates set to true.

For example:

net:

  ssl:

    mode: requireSSL

    PEMKeyFile: /etc/ssl/mongodb.pem

    CAFile: /etc/ssl/caToValidateClientCertificates.pem

    allowConnectionsWithoutCertificates: true

A mongod / mongos running with these settings allows connection from:

• Clients that do not present a certificate.
• Clients that present a valid certificate.

Note

If the client presents a certificate, the certificate must be a valid certificate.

All connections, including those that have not presented certificates, are encrypted using TLS/SSL.

See TLS/SSL Configuration for Clients for more information on TLS/SSL connections for clients.

See also:

You can also configure using the command-line options:

• For mongod, see --sslAllowConnectionsWithoutCertificates.
• For mongos, see --sslAllowConnectionsWithoutCertificates.

To prevent MongoDB servers from accepting incoming connections that use specific protocols, include net.ssl.disabledProtocols set to the disallowed protocols.

For example, the following configuration preventsmongod / mongos from accepting incoming connections that use either TLS1_0 or TLS1_1

net:

  ssl:

    mode: requireSSL

    PEMKeyFile: /etc/ssl/mongodb.pem

    CAFile: /etc/ssl/caToValidateClientCertificates.pem

    disabledProtocols: TLS1_0,TLS1_1

See also:

You can also configure using the command-line options:

• For mongod, see --sslDisabledProtocols.
• For mongos, see --sslDisabledProtocols.

If the certificate key files formongod / mongos are encrypted, includenet.ssl.PEMKeyPassword set to the passphrase.

See also:

You can also configure using the command-line options:

• For mongod, see sslPEMKeyPassword.
• For mongos, see --sslPEMKeyPassword.

Note

See Configure MongoDB for FIPS for more details.

To configure TLS/SSL support for clients, seeTLS/SSL Configuration for Clients.

See also: