Docs Menu
Docs Home
/
Languages
/
Java
/
Java Sync
/
Fundamentals
/
Connection Guide

Enable TLS/SSL on a Connection

On this page

  • Overview
  • Enable TLS/SSL
  • Configure Certificates
  • Configure the JVM Trust Store
  • Configure the JVM Key Store
  • Configure a Client-Specific Trust Store and Key Store
  • Disable Hostname Verification
  • Restrict Connections to TLS 1.2 Only
  • Customize TLS/SSL Configuration through the Java SE SSLContext
  • Customize TLS/SSL Configuration through the Netty SslContext
  • Online Certificate Status Protocol (OCSP)
  • Client-Driven OCSP
  • OCSP Stapling

Overview

In this guide, you can learn how to connect to MongoDB instances with the TLS/SSL security protocol using the underlying TLS/SSL support in the JDK. To configure your connection to use TLS/SSL, enable the TLS/SSL settings in either the ConnectionString or MongoClientSettings.

Note

Debugging TLS/SSL

If you experience trouble setting up your TLS/SSL connection, you can use the -Djavax.net.debug=all system property to view more log statements. See the Oracle guide to debugging TLS/SSL connections for more information.

Enable TLS/SSL

You can enable TLS/SSL for the connection to your MongoDB instance in two different ways: through a parameter in your connection string, or using a method in the MongoClientSettings.Builder class.

Note

If you connect by using the DNS seedlist protocol, indicated by the mongodb+srv prefix in your connection string, the driver enables TLS/SSL. To disable it, set the tls or ssl parameter value to false in your connection string or MongoClientSettings instance.

To learn more about connection behavior when you use a DNS seedlist, see the SRV Connection Format section in the Server manual.

To enable TLS/SSL on a connection with a ConnectionString, assign the connection string parameter tls a value of true in the connection string passed to MongoClients.create():

MongoClient mongoClient = MongoClients.create("mongodb+srv://<db_username>:<db_password>@<cluster-url>?tls=true");

To configure your MongoClient's TLS/SSL connection options using the MongoClientSettings.Builder class, call the applyToSslSettings() method. Set the enabled property to true in the SslSettings.Builder block to enable TLS/SSL:

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

Configure Certificates

Java applications that initiate TLS/SSL requests require access to cryptographic certificates that prove identity for the application itself and other applications with which the application interacts. You can configure access to these certificates in your application with the following mechanisms:

  • The JVM Trust Store and JVM Key Store

  • A Client-Specific Trust Store and Key Store

Note

The following sections are based on the documentation for Oracle JDK, so some parts may be inapplicable to your JDK or to the custom TLS/SSL implementation you use.

Configure the JVM Trust Store

Note

By default, the JRE includes many commonly used public certificates from signing authorities like Let's Encrypt. As a result, you can connect to instances of MongoDB Atlas (or any other server whose certificate is signed by an authority in the JRE's default certificate store) with TLS/SSL without configuring the trust store.

The JVM trust store saves certificates that securely identify other applications with which your Java application interacts. Using these certificates, your application can prove that the connection to another application is genuine and secure from tampering by third parties.

If your MongoDB instance uses a certificate that is signed by an authority that is not present in the JRE's default certificate store, your application must configure two system properties to initiate SSL/TLS requests. These properties ensure that your application can validate the TLS/SSL certificate presented by a connected MongoDB instance.

  • 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 the trust store defined in javax.net.ssl.trustStore

You can create a trust store with the keytool command line tool provided as part of the JDK:

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

Configure the JVM Key Store

Note

By default, MongoDB instances do not perform client certificate validation. You must configure the key store if you configured your MongoDB instance to validate client certificates.

The JVM key store saves certificates that securely identify your Java application to other applications. Using these certificates, other applications can prove that the connection to your application is genuine and secure from tampering by third parties.

An application that initiates TLS/SSL requests needs to set two JVM system properties to ensure that the client presents a TLS/SSL certificate to the MongoDB deployment:

  • 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 the key store defined in javax.net.ssl.keyStore

You can create a key store with the keytool or openssl command line tool.

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

Configure a Client-Specific Trust Store and Key Store

You can configure a client-specific trust store and key store using the init() method of the SSLContext class.

You can find an example showing how to configure a client with an SSLContext instance in the Customize TLS/SSL Configuration with an SSLContext section of this guide.

For more information on the SSLContext class, see the API documentation for SSL Context.

Disable Hostname Verification

By default, the driver ensures that the hostname included in the server's TLS/SSL certificates matches the hostnames provided when constructing a MongoClient. To disable hostname verification for your application, you can explicitly disable this by setting the invalidHostNameAllowed property of the builder to true in the applytoSslSettings() builder lambda:

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

Warning

Disabling hostname verification can make your configuration insecure. Disable hostname verification only for testing purposes or when there is no other alternative.

Restrict Connections to TLS 1.2 Only

To restrict your application to use only the TLS 1.2 protocol, set the jdk.tls.client.protocols system property to "TLSv1.2".

Note

Java Runtime Environments (JREs) before Java 8 only enabled the TLS 1.2 protocol in update releases. If your JRE has not enabled the TLS 1.2 protocol, upgrade to a later release to connect by using TLS 1.2.

Customize TLS/SSL Configuration through the Java SE SSLContext

If your TLS/SSL configuration requires customization, you can set the sslContext property of your MongoClient by passing an SSLContext object to the builder in the applyToSslSettings() lambda:

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

Customize TLS/SSL Configuration through the Netty SslContext

If you use the driver with Netty for network IO, you have an option to plug an alternative TLS/SSL protocol implementation provided by Netty.

import com.mongodb.MongoClientSettings;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;
import com.mongodb.connection.netty.NettyStreamFactoryFactory;
import io.netty.handler.ssl.SslContext;
import io.netty.handler.ssl.SslContextBuilder;
import io.netty.handler.ssl.SslProvider;

Note

The driver tests with Netty version io.netty:netty-all:4.1.79.Final

To instruct the driver to use io.netty.handler.ssl.SslContext, use the NettyStreamFactoryFactory.Builder.sslContext method. See the method documentation for details about the different io.netty.handler.ssl.SslProvider variants the driver supports and the implications of using them.

SslContext sslContext = SslContextBuilder.forClient()
        .sslProvider(SslProvider.OPENSSL)
        .build();
MongoClientSettings settings = MongoClientSettings.builder()
        .applyToSslSettings(builder -> builder.enabled(true))
        .streamFactoryFactory(NettyStreamFactoryFactory.builder()
                .sslContext(sslContext)
                .build())
        .build();
MongoClient client = MongoClients.create(settings);

Online Certificate Status Protocol (OCSP)

OCSP is a standard used to check whether X.509 certificates have been revoked. A certificate authority can add an X.509 certificate to the Certificate Revocation List (CRL) before the expiry time to invalidate the certificate. When a client sends an X.509 certificate during the TLS handshake, the CA's revocation server checks the CRL and returns a status of "good", "revoked", or "unknown".

The driver supports the following variations of OCSP:

  • Client-Driven OCSP

  • OCSP Stapling

The following sections describe the differences between them and how to enable them for your application.

Note

The Java driver uses the JVM arguments configured for the application and cannot be overridden for a specific MongoClient instance.

Client-Driven OCSP

In client-driven OCSP, the client sends the certificate in an OCSP request to an OCSP responder after receiving the certificate from the server. The OCSP responder checks the status of the certificate with a certificate authority (CA) and reports whether it's valid in a response sent to the client.

To enable client-driven OCSP for your application, set the following JVM system properties:

Property
Value
com.sun.net.ssl.checkRevocation
Set this property to true to enable revocation checking.
ocsp.enable
Set this property to true to enable client-driven OCSP.

Warning

If the OCSP responder is unavailable, the TLS support provided by the JDK reports a "hard fail". This differs from the "soft fail" behavior of the MongoDB Shell and some other drivers.

OCSP Stapling

OCSP stapling is a mechanism in which the server must obtain the signed certificate from the certificate authority (CA) and include it in a time-stamped OCSP response to the client.

To enable OCSP stapling for your application, set the following JVM system properties:

Property
Description
com.sun.net.ssl.checkRevocation
Set this property to true to enable revocation checking.
jdk.tls.client.enableStatusRequestExtension
Set this property to true to enable OCSP stapling.

If unset or set to false, the connection can proceed regardless of the presence or status of the certificate revocation response.

For more information about OCSP, check out the following resources:

Back

Network Compression

Next

Connect to MongoDB Using a JNDI Datasource