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 supportTLS/SSL. For instructions on upgrading a cluster currently not usingTLS/SSL to using TLS/SSL, see Upgrade a Cluster to Use TLS/SSLinstead.

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.0encryption on systems where TLS 1.1+ is available. Formore details, see Disable TLS 1.0.
MongoDB’s TLS/SSL encryption only allows the use of strong TLS/SSLciphers with a minimum of 128-bit key length for all connections.
The Linux 64-bit legacy x64 builds of MongoDB do not includesupport 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 certificatesgenerated and signed by a single certificate authority. You or yourorganization can generate and maintain an independent certificateauthority, or use certificates generated by a third-party TLS/SSLvendor. Obtaining and managing certificates is beyond the scope ofthis documentation.

mongod and mongos Certificate Key File

When establishing a TLS/SSL connection, themongod/mongos presents a certificate keyfile (containing a public key certificate and its associated privatekey) to its clients to establish its identity. [1]

MongoDB can use any valid TLS/SSL certificate issued by a certificateauthority, or a self-signed certificate. If you use a self-signedcertificate, although the communications channel will be encrypted toprevent eavesdropping on the connection, there will be no validationof server identity. This leaves you vulnerable to a man-in-the-middleattack. Using a certificate signed by a trusted certificate authoritywill permit MongoDB drivers to verify the server’s identity.

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

With regards to certificates for replica set and sharded clustermembers, it is advisable to use different certificates on differentservers. This minimizes exposure of the private key and allows forhostname validation.

[1]	For FIPS mode, ensure that the certificate is FIPS-compliant (i.euse of FIPS-compliant algorithms) and the private key meets thePKCS#8 standard. If you need to convert a private key to PKCS#8format, 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 (andcorresponding command-line options) that corresponds to thenet.ssl settings (and their corresponding command-lineoptions). The net.tls settings provide identical functionality asthe net.ssl options since MongoDB has always supported TLS1.0 and later.

The procedures in this section use the net.tls settings. Forprocedures 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 configuresmongod/mongos to use TLS/SSL connections.With these TLS/SSL settings,mongod/mongos presents its certificatekey file to the client. However, themongod/mongos does not require acertificate 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 (available starting inMongoDB 4.2). For procedures using the net.ssl settings, seeProcedures (Using net.ssl Settings).

To use TLS/SSL connections, include the following TLS/SSLsettings in yourmongod/mongos instance’sconfiguration 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/SSLencrypted connections. You can also specify either thevalue `allowTLS` or `preferTLS` to set up the useof 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/SSLcertificate and key.The `mongod`/`mongos`instance presents this file to its clients to establishthe 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

Starting in MongoDB 4.0, you can use system SSL certificate stores forWindows and macOS. To use the system SSL certificate store, specifynet.tls.certificateSelector instead of specifying thecertificate key file.

Setting	Notes
`net.tls.mode`	Set to `requireTLS`.This setting restricts each server to use only TLS/SSLencrypted connections. You can also specify either thevalue `allowTLS` or `preferTLS` to set up the useof 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:

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

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

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

See also

You can also configure mongod andmongos using command-line options instead of theconfiguration 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 configuresmongod/mongos to use TLS/SSL connectionsand perform client certificate validation. With these TLS/SSL settings:

mongod/mongos presents its certificatekey file to the client for verification.
mongod/mongos requires a certificatekey file from the client to verify the client’s identity.

Note

The procedure uses the net.tls settings (available starting inMongoDB 4.2). For procedures using the net.ssl settings, seeProcedures (Using net.ssl Settings).

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

Note

Starting in MongoDB 4.0, you can use system SSL certificate stores forWindows and macOS. To use the system SSL certificate store, specifynet.ssl.certificateSelector instead of specifying thecertificate key file.

Setting	Notes
`net.tls.mode`	Set to `requireTLS`.This setting restricts each server to use only TLS/SSLencrypted connections. You can also specify either thevalue `allowTLS` or `preferTLS` to set up the useof 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/SSLcertificate and key.The `mongod`/`mongos`instance presents this file to its clients to establishthe instance’s identity.
`net.tls.CAFile`	Set to the path of the file that contains the certificate chainfor verifying client certificates.The `mongod`/`mongos` instance usethis file to verify certificates presented by its clients. Thecertificate chain includes the certificate of the rootCertificate Authority.

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 configurationcan only use TLS/SSL connections and requires valid certificate fromits clients:

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

That is, clients must specify TLS/SSL connections and presents itscertificate key file to the instance. SeeConnect to MongoDB Instance that Requires Client Certificates (tls Options) for moreinformation on connecting with TLS/SSL.

See also

You can also configure mongod andmongos using command-line options instead of theconfiguration 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 inMongoDB 4.2). For procedures using the net.ssl settings, seeProcedures (Using net.ssl Settings).

To prevent clients with revoked certificates from connecting, includenet.tls.CRLFile set to a file that contains revokedcertificates.s

For example:

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 validcertificates. However, if you have clients that cannot present a clientcertificate or are transitioning to using a certificate, you may onlywant to validate certificates from clients that present a certificate.

Note

The procedure uses the net.tls settings (available starting inMongoDB 4.2). For procedures using the net.ssl settings, seeProcedures (Using net.ssl Settings).

To bypass client certificate validation for clients that do not presenta 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 thesesettings 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 avalid certificate.

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

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

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 inMongoDB 4.2). For procedures using the net.ssl settings, seeProcedures (Using net.ssl Settings).

To prevent MongoDB servers from accepting incoming connections that usespecific protocols, include net.tls.disabledProtocols set tothe disallowed protocols.

For example, the following configuration preventsmongod/mongos from accepting incomingconnections 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

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 formongod/mongos are encrypted, sincludenet.tls.certificateKeyFilePassword set to the passphrase.

Tip

Starting in MongoDB 4.2, to avoid specifying the passphrase incleartext, 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 isavailable only in MongoDB Enterprise. SeeConfigure MongoDB for FIPS for more information.

See Configure MongoDB for FIPS for more details.

Next Steps

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

Procedures (Using net.ssl Settings)

Note

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

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

To use TLS/SSL connections, include the following TLS/SSL settings inyour mongod/mongos instance’sconfiguration 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 encryptedconnections. 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/SSLcertificate and key.The `mongod`/`mongos` instancepresents this file to its clients to establish the instance’sidentity.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

Setting	Notes
`net.ssl.mode`	Set to `requireSSL`.This setting restricts each server to use only TLS/SSL encryptedconnections. 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 configurationcan only use TLS/SSL connections:

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

That is, clients must specify TLS/SSL connections. SeeConnect to MongoDB Instance Using Encryption (—ssl Options) for more information onconnecting 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.

Set Up mongod and mongos with Client Certificate Validation

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

mongod/mongos presents its certificatekey file to the client for verification.
mongod/mongos requires a certificatekey file from the client to verify the client’s identity.

To use TLS/SSL connections, include the following TLS/SSL settings inyour mongod/mongos instance’sconfiguration file:

Note

Setting	Notes
`net.ssl.mode`	Set to `requireSSL`.This setting restricts each server to use only TLS/SSL encryptedconnections. 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/SSLcertificate and key.The `mongod`/`mongos` instancepresents this file to its clients to establish the instance’sidentity.If the key is encrypted, specify the passphrase(`net.ssl.PEMKeyPassword`).
`net.ssl.CAFile`	Set to the path of the file that contains thecertificate chain for verifying client certificates.The `mongod`/`mongos`instance use this file to verify certificates presentedby its clients. The certificate chain includes thecertificate 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 configurationcan only use TLS/SSL connections and requires valid certificate fromits clients:

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

That is, clients must specify TLS/SSL connections and presents itscertificate key file to the instance. SeeConnect to MongoDB Instance that Requires Client Certificates (ssl Options) for moreinformation on connecting with TLS/SSL.

See also

You can also configure mongod andmongos using command-line options instead of theconfiguration 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, includenet.ssl.CRLFile set to a file that contains revokedcertificates.

For example:

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

To bypass client certificate validation for clients that do not presenta 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 thesesettings 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 avalid certificate.

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

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

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 usespecific protocols, include net.ssl.disabledProtocols set tothe disallowed protocols.

For example, the following configuration preventsmongod/mongos from accepting incomingconnections 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.

TLS/SSL Certificate Passphrase

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.

Run in FIPS Mode

Note

FIPS-compatible TLS/SSL isavailable only in MongoDB Enterprise. SeeConfigure MongoDB for FIPS for more information.

See Configure MongoDB for FIPS for more details.

Next Steps

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