X.509
On this page
Overview
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
Code Placeholders
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.
Using X.509 Authentication in Your Application
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>"]), };
Troubleshooting
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)); }
API Documentation
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: