TLS/SSL Configuration for Clients

Clients must have support for TLS/SSL to connect to amongod or a mongos instance that requireTLS/SSL connections.

Note

• The Linux 64-bit legacy x64 binaries of MongoDB do not includesupport for TLS/SSL.
• Starting in version 4.0, MongoDB disables support for TLS 1.0encryption on systems where TLS 1.1+ is available. Formore 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 (Using tls Options)

Note

Starting in version 4.2, MongoDB provides tls options thatcorresponds to the ssl options. The tls options provideidentical functionality as the ssl options since MongoDB hasalways supported TLS 1.0 and later.

The procedures in this section use the tls options. Forprocedures using their ssl aliases, seemongo Shell Configuration (Using ssl Options).

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

For a complete list of the mongo shell’s tlsoptions, see TLS Options.

For TLS/SSL connections, the mongo shell validates thecertificate presented by the mongod ormongos instance:

• The mongo shell verifies that the certificate is fromthe specified Certificate Authority (—tlsCAFile. If the certificate is not from the specified CA, themongo shell will fail to connect.

• The mongo shell verifies that the hostname (specifiedin —host option or the connection string)matches the SAN (or, if SAN is not present, the CN) inthe certificate presented by the mongod ormongos. If SAN is present, mongodoes not match against the CN. If the hostname does not matchthe SAN (or CN), the mongo shell will fail toconnect.

Starting in MongoDB 4.2, when performing comparison of SAN, MongoDBsupports comparison of DNS names or IP addresses. In previous versions,MongoDB only supports comparisons of DNS names.

To connect a mongo shell to a mongod ormongos that requires TLS/SSL, specify the—host option or use a connectionstring to specify the hostname. Allother TLS/SSL options must be specified using the command-lineoptions.

Connect to MongoDB Instance Using Encryption (tls Options)

Note

The procedure uses the tls options (available starting inMongoDB 4.2). For procedures using their ssl aliases, seemongo Shell Configuration (Using ssl Options).

To connect to a mongod or mongos instancethat requires encrypted communication,start the mongo shell with:

• —tls
• —host and —tlsCAFile to validate the server certificate.

For example, consider a mongod instance running onhostname.example.com with the following options:

mongod --tlsMode requireTLS --tlsCertificateKeyFile <pem>

To connect to the instance, start a mongo shell withthe following options:

mongo --tls --host hostname.example.com --tlsCAFile /etc/ssl/caToValidateServerCertificates.pem

The mongo shell verifies the certificate presented bythe mongod instance against the specified hostname andthe CA file.

Connect to MongoDB Instance that Requires Client Certificates (tls Options)

Note

The procedure uses the tls options (available starting inMongoDB 4.2). For procedures using their ssl aliases, seemongo Shell Configuration (Using ssl Options).

To connect to a mongod or mongos thatrequires CA-signed client certificates, start the mongoshell with:

• —tls
• —host and the —tlsCAFile to validate the server certificate,
• —tlsCertificateKeyFile option to specifythe client certificate to present to the server.

For example, consider a mongod instance running onhostname.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 thefollowing options:

mongo --tls --host hostname.example.com --tlsCertificateKeyFile /etc/ssl/client.pem --tlsCAFile /etc/ssl/caToValidateServerCertificates.pem

• On Windows and macOS,
• You can also use the —tlsCertificateSelector option to specify the client certificatefrom the system certificate store instead of using—tlsCertificateKeyFile. If the CA file is also in the systemcertificate store, you can omit the —tlsCAFile option as well. For example, to use a certificatewith the CN (Common Name) of myclient.example.net and the CAfile from the system certificate store on macOS, start amongo shell with the following options:

mongo --tls  --host hostname.example.com --tlsCertificateSelector subject="myclient.example.net"

Although still available, the mongo shell—ssl, —sslCAFile, —sslPEMKeyFile,—sslCertificateSelectorare deprecated as of MongoDB 4.2.

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 onsystems where intrusion is not possible.

If the mongo shell runs with the—tlsAllowInvalidCertificates option, the mongoshell will not attempt to validate the server certificates. Thiscreates a vulnerability to expired mongod andmongos certificates as well as to foreign processesposing as valid mongod or mongosinstances. If you only need to disable the validation of thehostname in the TLS/SSL certificates, see—tlsAllowInvalidHostnames.

mongo Shell Configuration (Using ssl Options)

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

For a complete list of the mongo shell’s ssloptions, see SSL Options.

For TLS/SSL connections, the mongo shell validates thecertificate presented by the mongod ormongos instance:

• The mongo shell verifies that the certificate is fromthe 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 (specifiedin —host option or the connection string)matches the SAN (or, if SAN is not present, the CN) inthe certificate presented by the mongod ormongos. If SAN is present, mongodoes not match against the CN. If the hostname does not matchthe SAN (or CN), the mongo shell will fail toconnect.

Starting in MongoDB 4.2, when performing comparison of SAN, MongoDBsupports comparison of DNS names or IP addresses. In previous versions,MongoDB only supports comparisons of DNS names.

To connect a mongo shell to a mongod ormongos that requires TLS/SSL, specify the—host option or use a connectionstring to specify the hostname. Allother TLS/SSL options must be specified using the command-lineoptions.

Connect to MongoDB Instance Using Encryption (—ssl Options)

Note

The procedure uses the ssl options. For procedures using thetls aliases (available starting in MongoDB 4.2), seemongo Shell Configuration (Using tls Options).

To connect to a mongod or mongos instancethat requires encrypted communication,start the mongo shell with:

• —ssl
• —host and —sslCAFile to validate the server certificate.

For example, consider a mongod instance running onhostname.example.com with the following options:

mongod --sslMode requireSSL --sslPEMKeyFile <pem>

To connect to the instance, start a mongo shell with thefollowing options:

mongo --ssl --host hostname.example.com --sslCAFile /etc/ssl/caToValidateServerCertificates.pem

The mongo shell verifies the certificate presented bythe mongod instance against the specified hostnameand the CA file.

Connect to MongoDB Instance that Requires Client Certificates (ssl Options)

Note

The procedure uses the ssl options. For procedures using thetls aliases (available starting in MongoDB 4.2), seemongo Shell Configuration (Using tls Options).

To connect to a mongod or mongos thatrequires CA-signed client certificates, start the mongoshell with:

• —ssl
• —host and the —sslCAFile to validate the server certificate,
• —sslPEMKeyFile option to specifythe client certificate to present to the server.

For example, consider a mongod instance running onhostname.example.com with the following options:

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem

To connect to the instance, start a mongo shell with thefollowing options:

mongo --ssl --host hostname.example.com --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem

• On Windows and macOS,
• You can also use the —sslCertificateSelector option to specify the client certificatefrom the system certificate store instead of using—sslPEMKeyFile. If the CA fileis also in the system certificate store, you can omit the—sslCAFile option as well. Forexample, to use a certificate with the CN (Common Name) ofmyclient.example.net and the CA file from the system certificatestore on macOS, start a mongo shell with thefollowing options:

mongo --ssl  --host hostname.example.com --sslCertificateSelector subject=myclient.example.net

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 optionon systems where intrusion is not possible.

If the mongo shell (and otherMongoDB Tools) runs with the—sslAllowInvalidCertificates option, themongo shell (and otherMongoDB Tools) will not attempt to validatethe server certificates. This creates a vulnerability to expiredmongod and mongos certificates aswell as to foreign processes posing as validmongod or mongos instances. If youonly need to disable the validation of the hostname in theTLS/SSL certificates, see —sslAllowInvalidHostnames.

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 communicationto gather its statistics. Because the agents already encryptcommunications to the MongoDB Cloud Manager/Ops Manager servers, this is just a matterof enabling TLS/SSL support in MongoDB Cloud Manager/Ops Manager on a per host basis.

For more information, see:

• MongoDB Atlas documentation
• MongoDB Cloud Manager documentation
• MongoDB Ops Manager documentation.

MongoDB Drivers

The MongoDB Drivers support encrypted communication. See:

MongoDB Tools

Various MongoDB utility programs support encrypted communication. Thesetools include:

To use encrypted communication with these tools, use the same ssl options asthe mongo shell. See mongo Shell Configuration (Using ssl Options).

See also

Configure mongod and mongos for TLS/SSL