Navigation
This version of the documentation is archived and no longer supported.

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. The current versions of the Python, Java, Ruby, Node.js, .NET, and C++ drivers have support for TLS/SSL, with full support coming in future releases of other drivers.

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

Although TLS is the successor to SSL, this page uses the more familiar term SSL to refer to TLS/SSL.

See also

Configure mongod and mongos for TLS/SSL.

mongo Shell SSL Configuration

For SSL connections, you must use the mongo shell built with SSL support or distributed with MongoDB Enterprise. To support SSL, mongo has the following settings:

  • --ssl

  • --sslPEMKeyFile with the name of the .pem file that contains the SSL certificate and key.

  • --sslCAFile with the name of the .pem file that contains the certificate from the Certificate Authority (CA).

    Warning

    If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

  • --sslPEMKeyPassword option if the client certificate-key file is encrypted.

Connect to MongoDB Instance with SSL Encryption

To connect to a mongod or mongos instance that requires only a SSL encryption mode, start mongo shell with --ssl, as in the following:

copy 
mongo --ssl

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 and the --sslPEMKeyFile option to specify the signed certificate-key file, as in the following:

copy 
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem

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 ssl and no certificate or with the --ssl ssl and a valid signed certificate.

For example, if mongod is running with weak certificate validation, both of the following mongo shell clients can connect to that mongod:

copy 
mongo --ssl
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem

Important

If the client presents a certificate, the certificate must be valid.

MongoDB Cloud Manager

The MongoDB Cloud Manager Monitoring agent will also have to connect via SSL in order to gather its statistics. Because the agent already utilizes SSL for its communications to the MongoDB Cloud Manager servers, this is just a matter of enabling SSL support in MongoDB Cloud Manager itself on a per host basis.

See the MongoDB Cloud Manager documentation for more information about SSL configuration.

PyMongo

Add the “ssl=True” parameter to a PyMongo MongoClient to create a MongoDB connection to an SSL MongoDB instance:

copy 
from pymongo import MongoClient
c = MongoClient(host="mongodb.example.net", port=27017, ssl=True)

To connect to a replica set, use the following operation:

copy 
from pymongo import MongoReplicaSetClient
c = MongoReplicaSetClient("mongodb.example.net:27017",
                          replicaSet="mysetname", ssl=True)

PyMongo also supports an “ssl=true” option for the MongoDB URI:

copy 
mongodb://mongodb.example.net:27017/?ssl=true

For more details, see the Python MongoDB Driver page.

Java

Consider the following example “SSLApp.java” class file:

copy 
import com.mongodb.*;
import javax.net.ssl.SSLSocketFactory;

public class SSLApp {

    public static void main(String args[])  throws Exception {

        MongoClientOptions o = new MongoClientOptions.Builder()
                .socketFactory(SSLSocketFactory.getDefault())
                .build();

        MongoClient m = new MongoClient("localhost", o);

        DB db = m.getDB( "test" );
        DBCollection c = db.getCollection( "foo" );

        System.out.println( c.findOne() );
    }
}

For more details, see the Java MongoDB Driver page.

Ruby

The recent versions of the Ruby driver have support for connections to SSL servers. Install the latest version of the driver with the following command:

copy 
gem install mongo

Then connect to a standalone instance, using the following form:

copy 
require 'rubygems'
require 'mongo'

connection = MongoClient.new('localhost', 27017, :ssl => true)

Replace connection with the following if you’re connecting to a replica set:

copy 
connection = MongoReplicaSetClient.new(['localhost:27017'],
                                       ['localhost:27018'],
                                       :ssl => true)

Here, mongod instance run on “localhost:27017” and “localhost:27018”.

For more details, see the Ruby MongoDB Driver page.

Node.JS (node-mongodb-native)

In the node-mongodb-native driver, use the following invocation to connect to a mongod or mongos instance via SSL:

copy 
var db1 = new Db(MONGODB, new Server("127.0.0.1", 27017,
                                     { auto_reconnect: false, poolSize:4, ssl:true } );

To connect to a replica set via SSL, use the following form:

copy 
var replSet = new ReplSetServers( [
    new Server( RS.host, RS.ports[1], { auto_reconnect: true } ),
    new Server( RS.host, RS.ports[0], { auto_reconnect: true } ),
    ],
  {rs_name:RS.name, ssl:true}
);

For more details, see the Node.JS MongoDB Driver page.

.NET

As of release 1.6, the .NET driver supports SSL connections with mongod and mongos instances. To connect using SSL, you must add an option to the connection string, specifying ssl=true as follows:

copy 
var connectionString = "mongodb://localhost/?ssl=true";
var server = MongoServer.Create(connectionString);

The .NET driver will validate the certificate against the local trusted certificate store, in addition to providing encryption of the server. This behavior may produce issues during testing if the server uses a self-signed certificate. If you encounter this issue, add the sslverifycertificate=false option to the connection string to prevent the .NET driver from validating the certificate, as follows:

copy 
var connectionString = "mongodb://localhost/?ssl=true&sslverifycertificate=false";
var server = MongoServer.Create(connectionString);

For more details, see the .NET MongoDB Driver page.

MongoDB Tools

Changed in version 2.6.

Various MongoDB utility programs supports SSL. These tools include:

To use SSL connections with these tools, use the same SSL options as the mongo shell. See mongo Shell SSL Configuration.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.