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

X.509

On this page

  • Overview
  • Code Placeholders
  • Using X.509 Authentication in Your Application
  • Troubleshooting
  • API Documentation

In the X.509 authentication mechanism, the server and client use the TLS protocol to exchange X.509 public-key certificates. You can use this mechanism to authenticate to MongoDB Atlas, MongoDB Enterprise Advanced, and MongoDB Community Edition.

Tip

X.509 Mechanism

To learn how to use TLS/SSL with the .NET/C# Driver, see TLS/SSL.

For more information about X.509 certificates, see X.509 in the MongoDB Server manual.

The code examples on this page use the following placeholders:

  • +srv: Include this option in your connection string prefix only if you are connecting to a MongoDB Atlas cluster. To learn more about the +srv option, see Connection String Formats in the MongoDB Server manual.

  • <hostname>: The network address of your MongoDB deployment.

  • <port>: The port number of the MongoDB deployment. If you omit this parameter, the driver uses the default port number (27017). You don't need a port number when connecting to a MongoDB Atlas cluster.

  • <X.509 certificate username>: The username of the user associated with the X.509 certificate. The username must match the distinguished subject name of the certificate. If you omit this parameter, the MongoDB deployment infers the username from the X.509 certificate.

  • <path to X.509 certificate>: The path to the X.509 certificate file.

  • <X.509 certificate password>: The password for the X.509 certificate.

To use the code examples on this page, replace these placeholders with your own values.

To use an X.509 certificate for authentication, you must use a MongoClientSettings object to specify the path to your X.509 certificate and the password for the certificate. The certificate must use the PKCS #12 (.p12) format.

Tip

Convert .pem to .p12

If your certificate uses the PEM (.pem) format, you must convert it to the .p12 format. To convert the certificate, use the openssl command-line tool, as shown in the following code example:

openssl pkcs12 -export -out <.p12 file> -inkey <private key file> -in <.pem file>

For more information about openssl-pkcs12, see the OpenSSL documentation.

You must also specify MONGODB-X509 as the authentication mechanism and $external as the authentication source. You can specify these options either in your connection string or by using a MongoCredential object. Select the Connection String or MongoCredential tab to see the corresponding syntax:

var connectionString = "mongodb[+srv]://<hostname>[:<port>]/?authSource=$external&authMechanism=MONGODB-X509";
var settings = MongoClientSettings.FromConnectionString(connectionString);
settings.UseTls = true;
settings.SslSettings = new SslSettings
{
ClientCertificates = new List<X509Certificate>()
{
new X509Certificate2("<path to X.509 certificate>", "<X.509 certificate password>")
}
};
var credential = MongoCredential.CreateMongoX509Credential("<X.509 certificate username>");
var settings = new MongoClientSettings
{
Credential = credential,
SslSettings = new SslSettings
{
ClientCertificates = new List<X509Certificate>()
{
new X509Certificate2("<path to X.509 certificate>", "<X.509 certificate password>")
},
},
UseTls = true,
Server = new MongoServerAddress("<hostname>"[, "<port>"]),
};

If you are using Windows as your operating system, you might encounter an issue in which the .NET/C# Driver is unable to locate an X.509 authentication certificate in memory. This error displays the following error message:

No credentials are available in the security package

To resolve this issue, add the following code to your application. This code generates any X.509 certificates required by your application and stores them to disk:

using (X509Certificate2 certWithKey = certOnly.CopyWithPrivateKey(key))
{
return new X509Certificate2(certWithKey.Export(X509ContentType.Pkcs12));
}

To learn more about any of the MongoDB methods and types used on this page, see the following API documentation:

For more information about the .NET types used on this page, see the following MSDN documentation:

Back

SCRAM