Docs Menu
Docs Home
/
Languages
/
PHP
/
Laravel MongoDB
/
Fundamentals
/
Connections

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 MongoDBDriverManager::__construct() API documentation.

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

Back

Connection Options

Next

Databases and Collections

On this page