For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.
- Java Driver
- Tutorials
- Connect to MongoDB
- TLS/SSL
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
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);
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()
.
If your application needs to disable hostname verification, you must explicitly indicate
this in MongoClientSettings
](/mongo-java-driver/4.0/apidocs/mongodb-driver-core/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/4.0/apidocs/mongodb-driver-core/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
.
Forcing TLS 1.2
Some applications may want to force only the TLS 1.2 protocol. To do this, set the jdk.tls.client.protocols
system property to “TLSv1.2”.
Java runtime environments prior to Java 8 started to enable the TLS 1.2 protocol only in later updates, as shown in the previous section. For the driver to force the use of the TLS 1.2 protocol with a Java runtime environment prior to Java 8, ensure that the update has TLS 1.2 enabled.