Enable TLS on a Connection

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 .NET framework. To configure your connection to use TLS/SSL, enable the TLS/SSL settings in either the connection string or MongoClientSettings.

Enable TLS

By default, TLS is disabled when connecting to MongoDB instances. You can enable TLS for the connection to your MongoDB instance in two different ways: using a property on a MongoClientSettings object or through a parameter in your connection string.

var settings = new MongoClientSettings { UseTls = true };
var client = new MongoClient(settings);

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>?tls=true");

Configure a Client Certificate

You can configure your X.509 certificate using MongoClientSettings. The following code sample creates a new X.509 certificate object using the certificate file named client.p12, which is protected by the password mySuperSecretPassword. The code then adds this certificate to the SslSettings.ClientCertificates array in MongoClientSettings.

var cert = new X509Certificate2("client.p12", "mySuperSecretPassword");
var settings = new MongoClientSettings
{
   SslSettings = new SslSettings
   {
      ClientCertificates = new[] { cert }
   },
   UseTls = true
};

Allow Insecure TLS

When TLS is enabled, the .NET/C# Driver automatically verifies the certificate that the server presents. When testing your code, you can disable certificate verification. This is known as insecure TLS.

When using insecure TLS, the only requirement is that the server present an X.509 certificate. The driver will accept a certificate even if any of the following are true:

• The hostname of the server and the subject name (or subject alternative name) on the certificate don't match.

• The certificate is expired or not yet valid.

• The certificate doesn't have a trusted root certificate in the chain.

• The certificate purpose isn't valid for server identification.

You can allow insecure TLS in two different ways: using a property on a MongoClientSettings object or through a parameter in your connection string.

var settings = new MongoClientSettings
{
   UseTls = true,
   AllowInsecureTls = true
};
var client = new MongoClient(settings);

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>?tls=true&tlsInsecure=true");

Check Certificate Revocation

When an X.509 certificate should no longer be trusted--for example, if its private key has been compromised--the certificate authority will revoke the certificate.

By default, the .NET/C# Driver doesn't check whether a server's certificate has been revoked before it connects. You can enable revocation checking using either MongoClientSettings or the connection string.

var settings = new MongoClientSettings
{
   SslSettings = new SslSettings
   {
      CheckCertificateRevocation = true
   },
   UseTls = true
};

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>?tls=true&tlsDisableCertificateRevocationCheck=false");

API Documentation

To learn more about any of the connection options discussed in this guide, see the following API documentation:

• MongoClientSettings