Navigation

TLS/SSL Configuration for Clients

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.

mongo Shell Configuration

For SSL connections, you must use the mongo shell built with SSL support or distributed with MongoDB Enterprise.

New in version 3.0: Most MongoDB distributions now include support for SSL.

The mongo shell provides various TLS/SSL Options settings, including:

  • --ssl
  • --sslPEMKeyFile with the name of the .pem file that contains the TLS/SSL certificate and key.
  • --sslPEMKeyPassword option if the client certificate-key file is encrypted.
  • --sslCAFile with the name of the .pem file that contains the certificate from the Certificate Authority (CA).

Changed in version 3.2.6: MongoDB 3.2.6 adds support for checking a certificate against the system CA store, allowing you to run the mongo shell with the --ssl option without including --sslCAFile or sslAllowInvalidCertificates.

If the mongod or mongos to which the mongo shell is connecting presents a certificate signed with a CA trusted by the operating system, the mongo shell will connect without error. In previous versions of MongoDB, the mongo shell exited with an error that it could not validate the certificate.

If your MongoDB deployment uses TLS/SSL, you must also specify the --host option. mongo verifies that the hostname of the mongod or mongos to which you are connecting matches the CN or SAN of the mongod or mongos’s --sslPEMKeyFile certificate. If the hostname does not match the CN/SAN, mongo will fail to connect.

Warning

For TLS/SSL connections (--ssl) to mongod and mongos, if the mongo shell (or MongoDB tools) runs with the --sslAllowInvalidCertificates option , the mongo shell (or 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. Only use --sslAllowInvalidCertificates on systems where intrusion is not possible.

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

Changed in version 3.2.6: MongoDB 3.2.6 adds support for checking a certificate against the system CA store, allowing you to run the mongo shell with the --ssl option without including --sslCAFile or sslAllowInvalidCertificates.

If the mongod or mongos to which the mongo shell is connecting presents a certificate signed with a CA trusted by the operating system, the mongo shell will connect without error. In previous versions of MongoDB, the mongo shell exited with an error that it could not validate the certificate.

If your MongoDB deployment uses TLS/SSL, you must also specify the --host option. mongo verifies that the hostname of the mongod or mongos to which you are connecting matches the CN or SAN of the mongod or mongos’s --sslPEMKeyFile certificate. If the hostname does not match the CN/SAN, mongo will fail to connect.

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

Changed in version 3.2.6: MongoDB 3.2.6 adds support for checking a certificate against the system CA store, allowing you to run the mongo shell with the --ssl option without including --sslCAFile or sslAllowInvalidCertificates.

If the mongod or mongos to which the mongo shell is connecting presents a certificate signed with a CA trusted by the operating system, the mongo shell will connect without error. In previous versions of MongoDB, the mongo shell exited with an error that it could not validate the certificate.

If your MongoDB deployment uses TLS/SSL, you must also specify the --host option. mongo verifies that the hostname of the mongod or mongos to which you are connecting matches the CN or SAN of the mongod or mongos’s --sslPEMKeyFile certificate. If the hostname does not match the CN/SAN, mongo will fail to connect.

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:

Changed in version 3.2.6: MongoDB 3.2.6 adds support for checking a certificate against the system CA store, allowing you to run the mongo shell with the --ssl option without including --sslCAFile or sslAllowInvalidCertificates.

If the mongod or mongos to which the mongo shell is connecting presents a certificate signed with a CA trusted by the operating system, the mongo shell will connect without error. In previous versions of MongoDB, the mongo shell exited with an error that it could not validate the certificate.

If your MongoDB deployment uses TLS/SSL, you must also specify the --host option. mongo verifies that the hostname of the mongod or mongos to which you are connecting matches the CN or SAN of the mongod or mongos’s --sslPEMKeyFile certificate. If the hostname does not match the CN/SAN, mongo will fail to connect.

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.

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.