Configure Transport Layer Security (TLS)

Overview

In this guide, you can learn how to use the Transport Layer Security (TLS) protocol to secure your connection to a MongoDB deployment.

When you enable TLS for a connection, the Scala driver performs the following actions:

• Uses TLS to connect to the MongoDB deployment

• Verifies the deployment's certificate

To learn how to configure your MongoDB deployment for TLS, see the TLS configuration guide in the MongoDB Server manual.

Enable TLS

You can enable TLS for the connection to your MongoDB deployment in the following ways:

• Use the enabled() method from the SslSettings.Builder class when creating a MongoClientSettings instance

• Set the tls parameter in your connection URI

Select the MongoClientSettings or Connection URI tab to see corresponding code that enables TLS:

val tlsUri = "mongodb://localhost:27017/"
val tlsSettings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString(tlsUri))
    .applyToSslSettings(builder => builder.enabled(true))
    .build()
val tlsClient1 = MongoClient(tlsSettings)

val tlsClient2 = MongoClient("mongodb://localhost:27017/?tls=true")

Configure Certificates

Scala applications that initiate TLS requests require access to cryptographic certificates that prove the application's identity and verify other applications with which the Scala application interacts. You can configure access to these certificates in your application in the following ways:

• Use a JVM trust store and JVM key store

• Use a client-specific trust store and key store

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

Disable Hostname Verification

By default, the driver ensures that the hostname included in the server's TLS certificates matches the hostnames provided when constructing a MongoClient. You can disable hostname verification in the following ways:

• Use the invalidHostNameAllowed() method from the SslSettings.Builder class when creating a MongoClientSettings instance

• Set the tlsAllowInvalidHostnames parameter in your connection URI

Select the MongoClientSettings or Connection URI tab to see corresponding code that disables hostname verification:

val invalidHostUri = "mongodb://localhost:27017/"
val invalidHostSettings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString(invalidHostUri))
    .applyToSslSettings(builder => builder
        .enabled(true)
        .invalidHostNameAllowed(true)
    )
    .build()
val invalidHostClient1 = MongoClient(invalidHostSettings)

val invalidHostClient2 = MongoClient("mongodb://localhost:27017/?tls=true&tlsAllowInvalidHostnames=true")

Restrict Connections to TLS 1.2

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

Customize Configuration with SSLContext

If your TLS configuration requires customization, you can set the sslContext property of your MongoClient object. Pass an SSLContext object to the context() method builder in the applyToSslSettings() block, as shown in the following code:

val sslContext = SSLContext.getDefault()
val contextSettings = MongoClientSettings.builder()
    .applyToSslSettings(builder => builder
        .enabled(true)
        .context(sslContext)
    )
    .build()
val mongoClient = MongoClient(contextSettings);

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

Online Certificate Status Protocol (OCSP)

OCSP is a standard used to check whether X.509 certificates have been revoked. A certificate authority (CA) 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 these variations and show how to enable them for your application.

API Documentation

For more information about any of the types discussed in this guide, see the following API documentation:

• ConnectionString

• MongoClientSettings