Enable and Configure TLS

On this page

Overview

Enable TLS
Configure Certificates
Reference Certificates
Additional Information

Overview

In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment. To configure your connection to use TLS, enable the TLS option and optionally provide your certificates for validation in your application's config/database.php file.

Tip

To learn more about TLS, see the Wikipedia entry on Transport Layer Security.

Enable TLS

In your application's config/database.php file, you can enable TLS on a connection to your MongoDB deployment in one of the following ways:

Setting the tls option to true in your connection string
Setting the tls option to true in the options property of your mongodb connection entry

Select from the following Connection String and Connection Options tabs to see a corresponding code sample:

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb://<hostname>:<port>/?tls=true',
        'database' => 'myDB',
    ]
]

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => '<connection string>',
        'database' => 'myDB',
        'options'  => [
            'tls' => true,
        ],
    ]
]

To view a full list of connection options, see Connection Options.

Note

If your connection string uses a DNS SRV record by including the mongodb+srv prefix, TLS is enabled on your connection by default.

Configure Certificates

To successfully initiate a TLS request, your application might need to present cryptographic certificates to prove its identity. Your application's certificates must be stored as PEM files to enable TLS when connecting.

Important

For production use, we recommend that your MongoDB deployment use valid certificates generated and signed by the same certificate authority. For testing, your deployment can use self-signed certificates.

The following list describes the components that your client can present to establish a TLS-enabled connection:

TLS Component	Description
Certificate Authority (CA)	One or more certificate authorities to trust when making a TLS connection. You can pass this file's path to the `tlsCAFile` option.
Client Certificate	A digital certificate that allows the server to verify the identity of your application to establish an encrypted network connection. You can pass this file's path to the `tlsCertificateKeyFile` option.
Certificate Key	The client certificate private key file. This key is often included within the certificate file itself. If you must provide this item, the certificate and key should be concatenated in one file that you can pass to the `tlsCertificateKeyFile` option.
Passphrase	The password to decrypt the private client key if it is encrypted. You can pass this file's path to the `tlsCertificateKeyFilePassword` option.

Reference Certificates

If required, you must reference your certificates when configuring your mongodb connection so that the server can validate them before the client connects.

We recommend that you reference your certificates and set other TLS options in the options property of your connection configuration instead of in the connection string. This improves code readability in your application.

Set the following options in the options property to reference your certificates:

tlsCAFile
tlsCertificateKeyFile
tlsCertificateKeyFilePassword

Note

For testing purposes, you can set the following options to true to disable validation:

tlsAllowInvalidCertificates
tlsAllowInvalidHostnames

Or, you can set the tlsInsecure option to true to implicitly set both of the preceding options.

Specifying these options in a production environment might make your application insecure. To learn more, see the Connection Options reference in the Server manual.

The following example configures a connection with TLS enabled:

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => '<connection string>',
        'database' => 'myDB',
        'options'  => [
            'tls' => true,
            'tlsCAFile' => '<path to CA certificate>',
            'tlsCertificateKeyFile' => '<path to private client certificate>',
            'tlsCertificateKeyFilePassword' => '<path to client key passphrase>',
        ]
    ]
]

Additional Information

To learn more about setting URI options, see the MongoDB\\Driver\\Manager::__construct() API documentation.

To learn more about enabling TLS on a connection, see the following Server manual documentation:

Back

Connection Options

Databases and Collections