Database Manual / Security / Encryption / TLS/SSL

Configure mongod and mongos for TLS/SSL on Self-Managed Deployments

Overview

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/SSL instead.

To set up a local development environment with TLS/SSL, see Developing MongoDB Locally with TLS.

MongoDB uses the native TLS/SSL OS libraries:

PlatformTLS/SSL Library

Windows

Secure Channel (Schannel)

Linux/BSD

OpenSSL

macOS

Secure Transport

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.

Prerequisites

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.

Certificate Authorities

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.

Member Certificate Requirements

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 the net.tls.clusterFile and net.tls.certificateKeyFile options. 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)

    MongoDB verifies that entries match exactly across all member certificates. If you list multiple OU values, all certificates must use an identical list.

    You can specify alternative attributes to use for authentication by setting net.tls.clusterAuthX509.extensionValue.

  • Cluster member configuration must include the same net.tls.clusterAuthX509.attributes and use matching values. Attribute order doesn't matter. The following example sets O and OU, but not DC:

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

Note

If you set the enforceUserClusterSeparation parameter to false, the following behaviors apply:

  • You cannot set clusterAuthMode to an option that allows X.509 or the server will not start. The server will only start if clusterAuthMode is keyFile.
  • A client can create a user in the $external database whose O/OU/DC attributes match the server's configured attributes for cluster membership.
  • A client presenting a member certificate can now attempt MONGODB-X509 authentication as a user in the $external database.

To set the enforceUserClusterSeparation parameter to false, 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 includes extendedKeyUsage, the value must include both clientAuth ("TLS Web Client Authentication") and serverAuth ("TLS Web Server Authentication").

    extendedKeyUsage = clientAuth, serverAuth

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

    extendedKeyUsage = clientAuth

mongod and mongos Certificate Key File

When establishing a TLS/SSL connection, the mongod / 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.

[1] For FIPS mode, ensure that the certificate is FIPS-compliant (i.e uses a FIPS-compliant algorithm) and the private key meets the PKCS#8 standard. If you need to convert a private key to PKCS#8 format, various conversion tools exist, such as openssl pkcs8 and others.

Procedures (Using net.tls Settings)

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 ssl settings 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).

Set Up mongod and mongos with TLS/SSL Certificate and Key

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

Note

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

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

SettingNotes

net.tls.mode

Set to requireTLS.

This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value allowTLS or preferTLS to set up the use of mixed TLS/SSL modes on a port. See net.tls.mode for details.

If you set --tlsMode to any value other than disabled, MongoDB uses the certificate specified in net.tls.certificateKeyFile for both server and client authentication in internal replica set connections. This certificate setting applies regardless of whether you set security.clusterAuthMode to X.509.

net.tls.certificateKeyFile

Set to the path of the file that contains the TLS/SSL certificate and key.

The mongod / mongos instance presents this file to its clients to establish the instance's identity.

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, specify net.tls.certificateSelector instead of specifying the certificate key file.




SettingNotes


net.tls.mode
Set to requireTLS.


This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value allowTLS or preferTLS to set up the use of mixed TLS/SSL modes on a port. See net.tls.mode for details.


If you set --tlsMode  to any value other than disabled, MongoDB uses the certificate specified in net.tls.certificateKeyFile for both server and client authentication in internal replica set connections. This certificate setting applies regardless of whether you set security.clusterAuthMode to X.509.


net.tls.certificateSelector
Set to the property (either subject or thumbprint) and value.


This setting is used to select the certificate. See net.tls.certificateSelector for details.
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.


Tip


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




Set Up mongod and mongos with Client Certificate Validation


The following section configures mongod / 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 the net.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's configuration 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.




SettingNotes


net.tls.mode
Set to requireTLS.


This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value allowTLS or preferTLS to set up the use of mixed TLS/SSL modes on a port. See net.tls.mode for details.


If you set --tlsMode  to any value other than disabled, MongoDB uses the certificate specified in net.tls.certificateKeyFile for both server and client authentication in internal replica set connections. This certificate setting applies regardless of whether you set security.clusterAuthMode to X.509.


net.tls.certificateKeyFile
Set to the path of the file that contains the TLS/SSL certificate and key.


The mongod / mongos instance presents this file to its clients to establish the instance's identity.


net.tls.CAFile
Set to the path of the file that contains the certificate chain for verifying client certificates.


The mongod / mongos instance use this file to verify certificates presented by its clients. The certificate chain includes the certificate of the root Certificate Authority.





Important


When starting a mongod instance with TLS/SSL enabled, you must specify a value for the --tlsCAFile flag, the net.tls.CAFile configuration option, or the tlsUseSystemCA parameter.


--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. See Connect to MongoDB Instances that Require Client Certificates for more information on connecting with TLS/SSL.


Tip


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




Block Revoked Certificates for Clients




Note


The procedure uses the net.tls settings. For procedures that use the net.ssl settings, see Procedures (Using net.ssl Settings).
To prevent clients with revoked certificates from connecting to the mongod or mongos instance, you can use a Certificate Revocation List (CRL).


To specify a CRL file, include net.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.


Tip


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




Validate Only if a Client Presents a Certificate


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 the net.ssl settings, see Procedures (Using net.ssl Settings).
To bypass client certificate validation for clients that do not present a certificate, include net.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.


Tip


You can also configure using the command-line options:




Disallow Protocols




Note


The procedure uses the net.tls settings. For procedures using the net.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 prevents mongod / 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


Tip


You can also configure using the command-line options:




TLS/SSL Certificate Passphrase


If the certificate key files for mongod / mongos are encrypted, include net.tls.certificateKeyFilePassword set to the passphrase.


Tip


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


Tip


You can also configure using the command-line options:




Online Certificate Rotation


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


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 the certificateKeyFilePassword configuration file setting). Certificate rotation does not support the interactive password prompt.
    2. 

  2. Connect mongosh to the mongod or mongos instance that you wish to perform certificate rotation on.
    3. 

  3. Run the rotateCertificates command or the db.rotateCertificates() shell method to rotate the certificates used by the mongod or mongos instance.
When certificate rotation takes place:


  • Existing connections to the mongod or mongos 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 or mongos 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.


Run in FIPS Mode




Note


FIPS-compatible TLS/SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.
See Configure MongoDB for FIPS for more details.


Next Steps


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


Tip


Use X.509 Certificates to Authenticate Clients on Self-Managed Deployments


Procedures (Using net.ssl Settings)




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 ssl
settings 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).


Set Up mongod and mongos with TLS/SSL Certificate and Key


The following section configures mongod / mongos to use TLS/SSL connections. With these TLS/SSL settings, mongod / mongos presents its certificate key file to the client. However, the mongod / mongos does not require a certificate key file from the client to verify the client's identity. To require client's certificate key file, see Set 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's configuration file:




SettingNotes


net.ssl.mode
Set to requireSSL.


This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify allowSSL or preferSSL
to use mixed TLS/SSL modes. See net.ssl.mode for details.


net.ssl.PEMKeyFile
Set to the .pem file that contains the TLS/SSL certificate and key.


The mongod / mongos instance presents this file to its clients to establish the instance's identity.


If the key is encrypted, specify the passphrase (net.ssl.PEMKeyPassword).
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, specify net.ssl.certificateSelector instead of specifying the certificate key file.




SettingNotes


net.ssl.mode
Set to requireSSL.


This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify allowSSL or preferSSL
to use mixed TLS/SSL modes. See net.ssl.mode for details.


net.ssl.certificateSelector
Set to the property (either subject or thumbprint) and value.


This setting is used to select the certificate. See net.ssl.certificateSelector for details.
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.


Tip


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


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

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


Set Up mongod and mongos with Client Certificate Validation


The following section configures mongod / 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's configuration 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.




SettingNotes


net.ssl.mode
Set to requireSSL.


This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify allowSSL or preferSSL
to use mixed TLS/SSL modes. See net.ssl.mode for details.


net.ssl.PEMKeyFile
Set to the .pem file that contains the TLS/SSL certificate and key.


The mongod / mongos instance presents this file to its clients to establish the instance's identity.


If the key is encrypted, specify the passphrase (net.ssl.PEMKeyPassword).


net.ssl.CAFile
Set to the path of the file that contains the certificate chain for verifying client certificates.


The mongod / mongos instance use this file to verify certificates presented by its clients. The certificate chain includes the certificate of the root Certificate Authority.
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. See Connect to MongoDB Instances that Require Client Certificates for more information on connecting with TLS/SSL.


Tip


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


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

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


Block Revoked Certificates for Clients


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


To specify a CRL file, include net.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.


Tip


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




Validate Only if a Client Presents a Certificate


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. 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.


To bypass client certificate validation for clients that do not present a certificate, include net.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


To use mongot with TLS, net.tls.allowConnectionsWithoutCertificates must be set to true. For details, see syncSource.replicaSet.tls.
See TLS/SSL Configuration for Clients for more information on TLS/SSL connections for clients.


Tip


You can also configure using the command-line options:


  • For mongod, see --sslAllowConnectionsWithoutCertificates.
    • 

  • For mongos, see --sslAllowConnectionsWithoutCertificates.


Disallow Protocols


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 prevents mongod / 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


Tip


You can also configure using the command-line options:


  • For mongod, see --sslDisabledProtocols.
    • 

  • For mongos, see --sslDisabledProtocols.


TLS/SSL Certificate Passphrase


If the certificate key files for mongod / mongos are encrypted, include net.ssl.PEMKeyPassword set to the passphrase.


Tip


You can also configure using the command-line options:


  • For mongod, see sslPEMKeyPassword.
    • 

  • For mongos, see --sslPEMKeyPassword.


Run in FIPS Mode




Note


FIPS-compatible TLS/SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.
See Configure MongoDB for FIPS for more details.


Next Steps


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


Tip


Use X.509 Certificates to Authenticate Clients on Self-Managed Deployments