Docs Menu
Docs Home
/ / /
C#/.NET
/ /

Enable TLS on a Connection

On this page

  • Overview
  • Enable TLS
  • Configure a Client Certificate
  • Allow Insecure TLS
  • Check Certificate Revocation
  • Revocation Checking by Operating System
  • API Documentation

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.

Important

TLS 1.2

The .NET/C# Driver supports only TLS 1.2 or higher.

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.

Note

If you connect by using the DNS seedlist protocol, the driver enables TLS/SSL by default. To disable it, set the tls or ssl parameter value to false in your connection string or MongoClientSettings instance.

To learn more about connection behavior when you use a DNS seedlist, see the SRV Connection Format section in the Server manual.

To enable TLS with a MongoClientSettings object, set the UseTls property to true:

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

To enable TLS with a connection string, assign the parameter tls a value of true in the connection string passed to the MongoClient constructor:

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

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
};

Important

When loading a certificate with a password, the certificate object must contain a private key. If it doesn't, your certificate will not be passed to the server.

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.

To allow insecure TLS with a MongoClientSettings object, set the AllowInsecureTls property to true:

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

To allow insecure TLS using a connection string, assign the connection string parameter tlsInsecure a value of true:

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

Warning

Always set this option to false in production. For security reasons, it's important that the server certificate is properly validated.

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.

To enable revocation checking using MongoClientSettings, set SslSettings.CheckCertificateRevocation to true:

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

To enable revocation checking using a connection string, assign the connection string parameter tlsDisableCertificateRevocationCheck a value of false:

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

Note

The .NET/C# Driver doesn't check revocation by default because this is the default behavior of the SslStream class in both the .NET framework and the .NET standard.

The .NET/C# Driver supports the following revocation-checking mechanisms differently on Windows, macOS, and Linux:

On Windows, the .NET/C# Driver supports OCSP, OCSP stapling, and CRLs without OCSP, in both the .NET Framework and .NET Core.

Warning

On Windows, the .NET/C# Driver will report a "hard fail" and cancel the TLS handshake if the OCSP responder is unavailable. Other operating systems and drivers will report a "soft fail" and continue connecting.

On macOS, the .NET/C# Driver supports OCSP and OCSP stapling.

Beginning with .NET Core 2.0, the driver does not support CRLs without OCSP.

On Linux, the .NET/C# Driver supports OCSP, OCSP stapling, and CRLs without OCSP.

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

Back

Connection Options