TLS/SSL

The Java driver supports TLS/SSL connections to MongoDB servers using the underlying support for TLS/SSL provided by the JDK. You can configure the driver to use TLS/SSL either with ConnectionString or with MongoClientSettings.

MongoClient API (since 3.7)

Specify TLS/SSL via ConnectionString

com.mongodb.reactivestreams.client.MongoClients;
com.mongodb.reactivestreams.client.MongoClient;

To specify TLS/SSL with ConnectionString, specify ssl=true as part of the connection string, as in:

MongoClient mongoClient = MongoClients.create("mongodb://localhost/?ssl=true");

Specify TLS/SSL via MongoClientSettings

import com.mongodb.MongoClientSettings;
import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoClient;

To specify TLS/SSL with with MongoClientSettings, set the enabled property to true, as in:

MongoClientSettings settings = MongoClientSettings.builder()
        .applyToSslSettings(builder -> builder.enabled(true))
        .build();
MongoClient client = MongoClients.create(settings);

Specify SSLContext via MongoClientSettings

import javax.net.ssl.SSLContext;
import com.mongodb.MongoClientSettings;
import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoClient;

To specify the javax.net.ssl.SSLContext with MongoClientSettings, set the sslContext property, as in:

SSLContext sslContext = ...
MongoClientSettings settings = MongoClientSettings.builder()
        .applyToSslSettings(builder -> {
                    builder.enabled(true);
                    builder.context(sslContext);
                })
        .build();
MongoClient client = MongoClients.create(settings);

Disable Hostname Verification

By default, the driver ensures that the hostname included in the server’s SSL certificate(s) matches the hostname(s) provided when constructing a MongoClient().

If your application needs to disable hostname verification, you must explicitly indicate this in MongoClientSettings](/mongo-java-driver/4.1/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html )

MongoClientSettings settings = MongoClientSettings.builder()
        .applyToSslSettings(builder -> {
                    builder.enabled(true);
                    builder.invalidHostNameAllowed(true);
                })
        .build();

JVM System Properties for TLS/SSL

A typical application will need to set several JVM system properties to ensure that the client is able to validate the TLS/SSL certificate presented by the server:

• javax.net.ssl.trustStore: The path to a trust store containing the certificate of the signing authority

• javax.net.ssl.trustStorePassword: The password to access this trust store

The trust store is typically created with the keytool command line program provided as part of the JDK. For example:

keytool -importcert -trustcacerts -file <path to certificate authority file>
            -keystore <path to trust store> -storepass <password>

A typical application will also need to set several JVM system properties to ensure that the client presents an TLS/SSL certificate to the MongoDB server:

• javax.net.ssl.keyStore The path to a key store containing the client’s TLS/SSL certificates

• javax.net.ssl.keyStorePassword The password to access this key store

The key store is typically created with the keytool or the openssl command line program.

For more information on configuring a Java application for TLS/SSL, please refer to the JSSE Reference Guide.