TLS/SSL Configuration for Clients
On this page
Clients must have support for TLS/SSL to connect to a
mongod or a mongos instance that require
TLS/SSL connections.
Note
The Linux 64-bit legacy x64 binaries of MongoDB do not include support for TLS/SSL.
MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.
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.
MongoDB Shell
The mongo shell provides various TLS/SSL settings,
including:
TLS Option (New in 4.2) | Notes |
|---|---|
Enables TLS/SSL connection. | |
Specifies the Changed in version 4.4: | |
If the mongo shell's certificate key file is encrypted. | |
If running on Windows or macOS, use a certificate from the system certificate store. (New in version 4.0) This option is mutually exclusive with
Changed in version 4.4: |
For a complete list of mongo shell's tls
options, see TLS options.
For TLS/SSL connections, the mongo shell validates the
certificate presented by the mongod or
mongos instance:
The
mongoshell verifies that the certificate is from the specified Certificate Authority (--tlsCAFile. If the certificate is not from the specified CA, themongoshell will fail to connect.The
mongoshell verifies that the hostname (specified in--hostoption or the connection string) matches theSAN(or, ifSANis not present, theCN) in the certificate presented by themongodormongos. IfSANis present,mongodoes not match against theCN. If the hostname does not match theSAN(orCN), themongoshell will fail to connect.Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names.
To connect a
mongoshell to amongodormongosthat requires TLS/SSL, specify the--hostoption or use a connection string to specify the hostname. All otherTLS/SSLoptions must be specified using the command-line options.
Connect to MongoDB Instances Using Encryption
To connect to a mongod or mongos instance
that requires encrypted communication,
start the mongo shell with:
--hostand--tlsCAFileto validate the server certificate.
For example, consider a mongod instance running on
hostname.example.com with the following options:
mongod --tlsMode requireTLS --tlsCertificateKeyFile <pem>
To connect to the instance, start a mongo shell with
the following options:
mongo --tls --host hostname.example.com --tlsCAFile /etc/ssl/caToValidateServerCertificates.pem
The mongo shell verifies the certificate presented by
the mongod instance against the specified hostname and
the CA file.
Connect to MongoDB Instances that Require Client Certificates
To connect to a mongod or mongos that
requires CA-signed client certificates, start the mongo
shell with:
--hostand the--tlsCAFileto validate the server certificate,--tlsCertificateKeyFileoption to specify the client certificate to present to the server.
For example, consider a mongod instance running on
hostname.example.com with the following options:
mongod --tlsMode requireTLS --tlsCertificateKeyFile /etc/ssl/mongodb.pem --tlsCAFile /etc/ssl/caToValidateClientCertificates.pem
To connect to the instance, start a mongo shell with the
following options:
mongo --tls --host hostname.example.com --tlsCertificateKeyFile /etc/ssl/client.pem --tlsCAFile /etc/ssl/caToValidateServerCertificates.pem
Windows and macOS
To specify a client certificate from the system certificate store, use
the --tlsCertificateSelector option instead of
--tlsCertificateKeyFile.
If the CA file is also in the system certificate store, you can omit the
--tlsCAFile option.
For example, if a certificate with the CN (Common Name) of
myclient.example.net and the accompanying CA file are both in the
macOS system certificate store, you can connect like this:
mongo --tls --host hostname.example.com --tlsCertificateSelector subject="myclient.example.net"
These options are deprecated starting in MongoDB 4.2:
--ssl--sslCAFile--sslPEMKeyFile--sslCertificateSelector
If possible, you should use the tls alternatives instead.
Avoid Use of --tlsAllowInvalidCertificates Option
Warning
Although available, avoid using the
--tlsAllowInvalidCertificates option if possible. If the use of
--tlsAllowInvalidCertificates is necessary, only use the option on
systems where intrusion is not possible.
If the mongo shell runs with the
--tlsAllowInvalidCertificates option, the mongo
shell will not attempt to validate the server certificates. This
creates a vulnerability to expired mongod and
mongos certificates as well as to foreign processes
posing as valid mongod or mongos
instances. If you only need to disable the validation of the
hostname in the TLS/SSL certificates, see
--tlsAllowInvalidHostnames.
MongoDB Atlas, MongoDB Cloud Manager and MongoDB Ops Manager
MongoDB Atlas uses TLS/SSL to encrypt the connections to your databases.
The MongoDB Cloud Manager and Ops Manager Monitoring agents use encrypted communication to gather its statistics. Because the agents already encrypt communications to the MongoDB Cloud Manager/Ops Manager servers, this is just a matter of enabling TLS/SSL support in MongoDB Cloud Manager/Ops Manager on a per host basis.
For more information, see:
MongoDB Drivers
The MongoDB Drivers support encrypted communication. See:
MongoDB Tools
Various MongoDB utility programs support encrypted communication. These tools include:
To use encrypted communication with these tools, use the same tls options as
mongo. See MongoDB Shell.