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

import org.mongodb.scala._

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

val mongoClient: MongoClient = MongoClient("mongodb://localhost/?ssl=true")

Specify TLS/SSL via MongoClientSettings

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

val settings = MongoClientSettings.builder()
    .applyToSslSettings((builder: SslSettings.Builder) => builder.enabled(true))
    .build()
val client = MongoClients.create(settings)

Specify SSLContext via MongoClientSettings

import javax.net.ssl.SSLContext

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

val sslContext: SSLContext = ???
val settings = MongoClientSettings.builder()
    .applyToSslSettings((builder: SslSettings.Builder) => {
        builder.enabled(true)
        builder.context(sslContext)
    })
    .build()
val 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/mongo-scala-driver/org/mongodb/scala/MongoClientSettings$.html )

val settings = MongoClientSettings.builder()
    .applyToSslSettings((builder: SslSettings.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.