For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.
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
.
With the legacy MongoClient API you can use either MongoClientURI
or
MongoClientOptions
.
MongoClient API (since 3.7)
Specify TLS/SSL via ConnectionString
com.mongodb.client.MongoClients;
com.mongodb.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.client.MongoClients;
import com.mongodb.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.client.MongoClients;
import com.mongodb.client.MongoClient;
To specify the javax.net.ssl.SSLContext
with
MongoClientOptions
, 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);
Legacy MongoClient API
Specify TLS/SSL via MongoClientURI
import com.mongodb.MongoClientURI;
import com.mongodb.MongoClient;
To specify TLS/SSL with MongoClientURI
, specify ssl=true
as part of the connection
string, as in:
MongoClientURI uri = new MongoClientURI("mongodb://localhost/?ssl=true");
MongoClient mongoClient = new MongoClient(uri);
Specify TLS/SSL via MongoClientOptions
import com.mongodb.MongoClientOptions;
import com.mongodb.MongoClient;
To specify TLS/SSL with with MongoClientOptions
, set the sslEnabled
property to true
, as in:
MongoClientOptions options = MongoClientOptions.builder()
.sslEnabled(true)
.build();
MongoClient client = new MongoClient("localhost", options);
Specify SSLContext
via MongoClientOptions
import javax.net.ssl.SSLContext;
import com.mongodb.MongoClientOptions;
import com.mongodb.MongoClient;
To specify the javax.net.ssl.SSLContext
with
MongoClientOptions
, set the sslContext
property, as in:
SSLContext sslContext = ...
MongoClientOptions options = MongoClientOptions.builder()
.sslEnabled(true)
.sslContext(sslContext)
.build();
MongoClient client = new MongoClient("localhost", options);
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()
. However, the hostname verification
requires a Java 7 JVM, as it relies on additions introduced in Java 7
to the javax.net.SSLParameters
class.
If your application must run on Java 6, or for some other reason you
need to disable hostname verification, you must explicitly indicate
this in MongoClientSettings
](/mongo-java-driver/3.10/javadoc?com/mongodb/MongoClientSettings.html
)
MongoClientSettings settings = MongoClientSettings.builder()
.applyToSslSettings(builder -> {
builder.enabled(true);
builder.invalidHostNameAllowed(true);
})
.build();
or, with the legacy MongoClientOptions
](/mongo-java-driver/3.10/javadoc?com/mongodb/MongoClientOptions.html
), using the sslInvalidHostNameAllowed
property:
MongoClientOptions.builder()
.sslEnabled(true)
.sslInvalidHostNameAllowed(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 authorityjavax.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 certificatesjavax.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
.
JVM Support for TLS v1.1 and newer
Industry best practices recommend, and some regulations require, the use of TLS 1.1 or newer. Though no application changes are required for the driver to make use of the newest TLS protocols, Java runtime environments prior to Java 8 started to enable TLS 1.1 only in later updates:
Java 7
- Starting with Update 131, released October 8, 2016, TSL 1.1 and TLS 1.2 are enabled by default.
- Starting with
Update 95,
released January 19, 2016, TLS 1.1 and TLS 1.2 can be enabled by applications via the
jdk.tls.client.protocols
system property.
Java 6
- Starting with Update 141, released on January 17, 2017, TSL 1.1 and TLS 1.2 are enabled by default.
- Starting with
Update 115 b32, released July 19, 2016,
TLS 1.1 and TLS 1.2 can be enabled by applications via the
jdk.tls.client.protocols
system property.
Note that these updates are only available from Oracle via its Java SE commercial support program. Java 7 Update 131 is available via OpenJDK.