- Security >
- TLS/SSL (Transport Encryption) >
- TLS/SSL Configuration for Clients
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.
- 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.
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.
mongo
Shell Configuration¶
The mongo
shell provides various TLS/SSL Options
settings, including:
Option | Notes |
---|---|
--ssl |
Enables TLS/SSL connection. |
--sslPEMKeyFile |
Specifies the .pem file that contains the
mongo shell’s certificate and key to present to
the mongod or mongos instance. |
--sslPEMKeyPassword |
If the mongo shell’s .pem file is encrypted. |
--sslCAFile |
Specifies the Certificate Authority (CA) .pem file for
verification of the certificate presented by the
mongod or the mongos instance. |
--sslCertificateSelector |
If running on Windows or macOS, instead of specifying a
certificate with --sslPEMKeyFile , use a certificate from the system certificate
store. (New in version 4.0) |
For a complete list of the mongo
shell’s TLS/SSL settings, see
TLS/SSL Options.
For TLS/SSL connections, the mongo
shell validates the
certificate presented by the mongod
or
mongos
instance:
The
mongo
shell verifies that the certificate is from the specified Certificate Authority (--sslCAFile
). If the certificate is not from the specified CA, themongo
shell will fail to connect.The
mongo
shell verifies that the hostname (specified in--host
option or the connection string) matches theSAN
(or, ifSAN
is not present, theCN
) in the certificate presented by themongod
ormongos
. IfSAN
is present,mongo
does not match against theCN
. If the hostname does not match theSAN
(orCN
), themongo
shell will fail to connect.To connect a
mongo
shell to amongod
ormongos
that requires TLS/SSL, specify the--host
option or use a connection string.
Connect to MongoDB Instance Using Encryption¶
To connect to a mongod
or mongos
instance
that requires encrypted communication,
start mongo
shell with:
--ssl
--host
and--sslCAFile
to validate the server certificate.
For example, consider a mongod
instance running on
hostname.example.com
with the following options:
To connect to the instance, start a mongo
shell with the
following options:
The mongo
shell verifies the certificate presented by
the mongod
instance against the specified hostname and
the CA file.
Connect to MongoDB Instance that Requires Client Certificates¶
To connect to a mongod
or mongos
that requires
CA-signed client certificates, start the mongo
shell
with:
--ssl
--host
and the--sslCAFile
to validate the server certificate,--sslPEMKeyFile
option 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:
To connect to the instance, start a mongo
shell with the
following options:
- On Windows and macOS,
You can also use the
--sslCertificateSelector
option to specify the client certificate from the system certificate store instead of using--sslPEMKeyFile
. If the CA file is also in the system certificate store, you can omit the--sslCAFile
option as well. For example, to use a certificate with theCN
(Common Name) ofmy.client.server
and the CA file from the system certificate store on macOS, start amongo
shell with the following options:
Avoid Use of --sslAllowInvalidCertificates
Option¶
Warning
Although available, avoid using the
--sslAllowInvalidCertificates
option if possible. If the use of
--sslAllowInvalidCertificates
is necessary, only use the option
on systems where intrusion is not possible.
If the mongo
shell (and other
MongoDB Tools) runs with the
--sslAllowInvalidCertificates
option, the
mongo
shell (and other
MongoDB Tools) 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 --sslAllowInvalidHostnames
.
MongoDB Atlas, MongoDB Cloud Manager and Ops Manager Monitoring Agent¶
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/SSL options as
the mongo
shell. See mongo Shell Configuration.