TLS/SSL Configuration for Clients
On this page
Clients must have support for TLS/SSL to work with a mongod or a mongos instance that has TLS/SSL support enabled.
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.
Note
TLS is the successor to SSL.
See also
mongo Shell Configuration
Note
The Linux 64-bit legacy x64 builds of MongoDB do not include support for TLS/SSL.
The mongo shell provides various TLS/SSL Options settings, including:
--ssl--sslPEMKeyFilewith the name of the.pemfile that contains the TLS/SSL certificate and key.--sslPEMKeyPasswordoption if the client certificate-key file is encrypted.--sslCAFilewith the name of the.pemfile that contains the certificate from the Certificate Authority (CA).
To connect to a mongod or mongos that uses TLS/SSL, you must also specify the --host option for the mongo shell if you haven’t specified a connect string. The mongo shell verifies that the hostname (specified in --host option or the connection string) matches the SAN (or, if SAN is not present, the CN) in the certificate presented by the mongod or mongos. If SAN is present, mongo does not match against the CN. If the hostname does not match the SAN (or CN), the mongo shell will fail to connect.
For a complete list of the mongo shell’s TLS/SSL settings, see TLS/SSL Options.
Connect to MongoDB Instance Using Encryption
To connect to a mongod or mongos instance that requires encrypted communication, start mongo shell with --ssl and include the --sslCAFile to validate the server certificates.
mongo --ssl --host hostname.example.com --sslCAFile /etc/ssl/ca.pem
Warning
For TLS/SSL connections to mongod and mongos, avoid using --sslAllowInvalidCertificates if possible and only use --sslAllowInvalidCertificates 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.
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, the --host option to specify the host to which to connect, the --sslPEMKeyFile option to specify the signed certificate-key file, and the --sslCAFile to validate the server certificates.
mongo --ssl --host hostname.example.com --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem
Warning
For TLS/SSL connections to mongod and mongos, avoid using --sslAllowInvalidCertificates if possible and only use --sslAllowInvalidCertificates 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.
Connect to MongoDB Instance that Validates when Presented with a Certificate
To connect to a mongod or mongos instance that only requires valid certificates when the client presents a certificate, start mongo shell either:
- with the
--ssl,--sslCAFile, and no certificate or - with the
--ssl,--sslCAFile, and a valid signed certificate.
Warning
For TLS/SSL connections to mongod and mongos, avoid using --sslAllowInvalidCertificates if possible and only use --sslAllowInvalidCertificates 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.
For example, if mongod is running with weak certificate validation, both of the following mongo shell clients can connect to that mongod:
mongo --ssl --host hostname.example.com --sslCAFile /etc/ssl/ca.pem
mongo --ssl --host hostname.example.com --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem
Important
If the client presents a certificate, the certificate must be valid.
MongoDB Cloud Manager and Ops Manager Monitoring Agent
The MongoDB Cloud Manager and Ops Manager Monitoring agents will also have to use encrypted communication in order to gather its statistics. Because the agents already encrypted 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.
See the MongoDB Cloud Manager documentation for more information about TLS/SSL configuration.
For Ops Manager, see Ops Manager documentation .