• Security >
• TLS/SSL (Transport Encryption) >
• Configure mongod and mongos for TLS/SSL

Configure mongod and mongos for TLS/SSL

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.

Starting in version 4.0, MongoDB uses the native TLS/SSL OS libraries:

Windows	Secure Channel (Schannel)
Linux/BSD	OpenSSL
macOS	Secure Transport

Note

• Starting in version 4.0, MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.
• 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 single certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by a third-party TLS/SSL vendor. Obtaining and managing certificates is beyond the scope of this documentation.

mongod and mongos Certificate Key File

When establishing a TLS/SSL connection, the mongod/mongos presents a certificate key file (containing a public key certificate and its associated private key) to its clients to establish its identity. [1]

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.

[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

Starting in version 4.2, MongoDB provides net.tls settings (and corresponding command-line options) that corresponds to the net.ssl settings (and their corresponding command-line options). The net.tls settings provide identical functionality as the net.ssl options 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 (available starting in MongoDB 4.2). For procedures using 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:

• PEMKeyFile (Linux/Windows/macOS)
• System SSL Certificate Store(Windows/macOS)

Setting	Notes
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.
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:

copy

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

Starting in MongoDB 4.0, 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.

Setting	Notes
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.
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:

copy

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 use TLS/SSL connections:

copy

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

That is, clients must specify TLS/SSL connections. See Connect to MongoDB Instance Using Encryption (tls Options) for more information on connecting with TLS/SSL.

See also

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

• For mongod, see: --tlsMode; --tlsCertificateKeyFile; and --tlsCertificateSelector.
• For mongos, see: --tlsMode; --tlsCertificateKeyFile; and --tlsCertificateSelector.

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 (available starting in MongoDB 4.2). For procedures using 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

Starting in MongoDB 4.0, 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.

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

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

copy

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 use TLS/SSL connections and requires valid certificate from its clients:

copy

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

That is, clients must specify TLS/SSL connections and presents its certificate key file to the instance. See Connect to MongoDB Instance that Requires Client Certificates (tls Options) for more information on connecting with TLS/SSL.

See also

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

• For mongod, see --tlsMode, --tlsCertificateKeyFile, and --tlsCAFile.
• For mongos, see --tlsMode, --tlsCertificateKeyFile, --tlsCAFile.

Block Revoked Certificates for Clients

Note

The procedure uses the net.tls settings (available starting in MongoDB 4.2). For procedures using 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:

• Online Certificate Status Protocol (OCSP)

  Starting in version 4.4, to check for certificate revocation, MongoDB enables the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store.

  In versions 4.0 and 4.2, the use of OCSP is available only through the use of system certificate store on Windows or macOS.

• Certificate Revocation List (CRL)

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

  For example:

  copy

  net:
    tls:
      mode: requireTLS
      certificateKeyFile: /etc/ssl/mongodb.pem
      CAFile: /etc/ssl/caToValidateClientCertificates.pem
      CRLFile: /etc/ssl/revokedCertificates.pem
  

  Clients who presents certificates that are listed in the /etc/ssl/revokedCertificates.pem will not be able to connect.

  See also

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

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

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 (available starting in MongoDB 4.2). 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:

copy

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

You can also configure using the command-line options:

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

Disallow Protocols

Note

The procedure uses the net.tls settings (available starting in MongoDB 4.2). 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

copy

net:
  tls:
    mode: requireTLS
    certificateKeyFile: /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 --tlsDisabledProtocols.
• For mongos, see --tlsDisabledProtocols.

TLS/SSL Certificate Passphrase

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

Tip

Starting in MongoDB 4.2, to avoid specifying the passphrase in cleartext, you can use an expansion value in the configuration file.

See also

You can also configure using the command-line options:

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

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.

See also

Use x.509 Certificates to Authenticate Clients

Procedures (Using net.ssl Settings)

Note

Starting in version 4.2, MongoDB provides net.tls settings (and corresponding command-line options) that corresponds to the net.ssl settings (and their corresponding command-line options). The net.tls settings provide identical functionality as the net.ssl options 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:

• PEMKeyFile (Linux/Windows/macOS)
• System SSL Certificate Store(Windows/macOS)

Setting	Notes
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:

copy

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

Starting in MongoDB 4.0, 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.

Setting	Notes
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:

copy

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 use TLS/SSL connections:

copy

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

That is, clients must specify TLS/SSL connections. See Connect to MongoDB Instance Using Encryption (--ssl Options) for more information on connecting with TLS/SSL.

See also

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

Starting in MongoDB 4.0, 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.

Setting	Notes
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:

copy

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 use TLS/SSL connections and requires valid certificate from its clients:

copy

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

That is, clients must specify TLS/SSL connections and presents its certificate key file to the instance. See Connect to MongoDB Instance that Requires Client Certificates (ssl Options) for more information on connecting with TLS/SSL.

See also

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:

• Online Certificate Status Protocol (OCSP)

  Starting in version 4.4, to check for certificate revocation, MongoDB enables the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store.

  In versions 4.0 and 4.2, the use of OCSP is available only through the use of system certificate store on Windows or macOS.

• Certificate Revocation List (CRL)

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

  For example:

  copy

  net:
    ssl:
      mode: requireSSL
      PEMKeyFile: /etc/ssl/mongodb.pem
      CAFile: /etc/ssl/caToValidateClientCertificates.pem
      CRLFile: /etc/ssl/revokedCertificates.pem
  

  Clients who presents certificates that are listed in the /etc/ssl/revokedCertificates.pem will not be 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.

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.

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

For example:

copy

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.

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

copy

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.

TLS/SSL Certificate Passphrase

If the certificate key files for mongod/mongos are encrypted, include net.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.

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.

See also

Use x.509 Certificates to Authenticate Clients

←   TLS/SSL (Transport Encryption) TLS/SSL Configuration for Clients  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.