Docs Home → Develop Applications → MongoDB Manual
Configure mongod
and mongos
for TLS/SSL![](/docs/v5.2/assets/link.svg)
On this page
Overview![](/docs/v5.2/assets/link.svg)
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.
MongoDB uses the native TLS/SSL OS libraries:
Platform | TLS/SSL Library |
---|---|
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![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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.
mongod
and mongos
Certificate Key File![](/docs/v5.2/assets/link.svg)
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.
[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)![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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:
A mongod
instance that uses the above configuration
can only use TLS/SSL connections:
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.
Tip
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![](/docs/v5.2/assets/link.svg)
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 |
---|---|
Set to This setting restricts each server to use only TLS/SSL
encrypted connections. You can also specify either the
value | |
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 use TLS/SSL connections and requires valid certificate from
its clients:
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.
Tip
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![](/docs/v5.2/assets/link.svg)
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 thesystem 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:
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.Tip
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![](/docs/v5.2/assets/link.svg)
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:
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
See also:
You can also configure using the command-line options:
Disallow Protocols![](/docs/v5.2/assets/link.svg)
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
net: tls: mode: requireTLS certificateKeyFile: /etc/ssl/mongodb.pem CAFile: /etc/ssl/caToValidateClientCertificates.pem disabledProtocols: TLS1_0,TLS1_1
Tip
See also:
You can also configure using the command-line options:
For
mongod
, see--tlsDisabledProtocols
.For
mongos
, see--tlsDisabledProtocols
.
TLS/SSL Certificate Passphrase![](/docs/v5.2/assets/link.svg)
If the certificate key files for
mongod
/mongos
are encrypted, include
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.
Tip
See also:
You can also configure using the command-line options:
For
mongod
, see--tlsCertificateKeyFilePassword
.For
mongos
, see--tlsCertificateKeyFilePassword
.
Online Certificate Rotation![](/docs/v5.2/assets/link.svg)
Starting in MongoDB 5.0, you can rotate the following certificate key files on-demand:
CRL (Certificate Revocation List) files
(on Linux and Windows platforms)
To rotate one or more of these certificates:
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.
Connect
mongosh
to themongod
ormongos
instance that you wish to perform certificate rotation on.Run the
rotateCertificates
command or thedb.rotateCertificates()
shell method to rotate the certificates used by the themongod
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
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![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
To configure TLS/SSL support for clients, see TLS/SSL Configuration for Clients.
Tip
Procedures (Using net.ssl
Settings)![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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:
A mongod
instance that uses the above configuration
can only use TLS/SSL connections:
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.
Tip
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![](/docs/v5.2/assets/link.svg)
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 |
---|---|
Set to This setting restricts each server to use only TLS/SSL encrypted
connections. You can also specify | |
Set to the The If the key is encrypted, specify the passphrase
( | |
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 use TLS/SSL connections and requires valid certificate from
its clients:
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.
Tip
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![](/docs/v5.2/assets/link.svg)
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 thesystem 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:
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.Tip
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![](/docs/v5.2/assets/link.svg)
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:
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.
Tip
See also:
You can also configure using the command-line options:
Disallow Protocols![](/docs/v5.2/assets/link.svg)
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
See also:
You can also configure using the command-line options:
For
mongod
, see--sslDisabledProtocols
.For
mongos
, see--sslDisabledProtocols
.
TLS/SSL Certificate Passphrase![](/docs/v5.2/assets/link.svg)
If the certificate key files for
mongod
/mongos
are encrypted, include
net.ssl.PEMKeyPassword
set to the passphrase.
Tip
See also:
You can also configure using the command-line options:
For
mongod
, see--sslPEMKeyPassword
.For
mongos
, see--sslPEMKeyPassword
.
Run in FIPS Mode![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
To configure TLS/SSL support for clients, see TLS/SSL Configuration for Clients.