X.509 Authentication Mechanism

On this page

Overview

Code Placeholders
Specify X.509 Authentication
TLS Options

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

To learn how to use TLS/SSL with the Node.js driver, see the Enable TLS on a Connection guide.

For more information about X.509 certificates, see Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments in the MongoDB Server manual.

Code Placeholders

The code examples on this page use the following placeholders:

<cluster_url>: The network address of your MongoDB deployment.
<pem_certificate_file_path>: The path to your client PEM certificate file.

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

Specify X.509 Authentication

You can specify this authentication mechanism by setting the following parameters of your connection string:

Set the authMechanism parameter to MONGODB-X509
Set the tls parameter to true

Pass the location of your client certificate file as the value of tlsCertificateKeyFile as a parameter of the connection URI.

Important

Always URI encode the certificate file path using the encodeURIComponent method to ensure it is parsed correctly.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const clusterUrl = "<cluster_url>";
const clientPEMFile = encodeURIComponent("<pem_certificate_file_path>");
const authMechanism = "MONGODB-X509";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${clusterUrl}/?authMechanism=${authMechanism}&tls=true&tlsCertificateKeyFile=${clientPEMFile}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

TLS Options

The following table describes the TLS options that you can set in a connection URI.

Parameter Name	Type	Default Value	Description
`tls`	boolean	`false`	Specifies whether to enable TLS on the connection.
`tlsInsecure`	boolean	`false`	Specifies whether to allow invalid certificates and mismatched hostnames. When set to `true`, this is equivalent to setting `tlsAllowInvalidCertificates` and `tlsAllowInvalidHostnames` to `true`.
`tlsCAFile`	string		Path to file that contains a single or bundle of trusted certificate authorities used in a TLS connection.
`tlsCertificateKeyFile`	string		Path to the client certificate file or the client private key file. If both are required, the two must be concatenated into a single file.
`tlsCertificateKeyFilePassword`	buffer or string		String or buffer that contains the password to decrypt the client private key.
`tlsAllowInvalidCertificates`	boolean	`false`	Specifies whether the driver permits an invalid certificate to be used to connect.
`tlsAllowInvalidHostnames`	boolean	`false`	Specifies whether the driver raises an error when there is a mismatch between the server hostname and TLS certificate hostname.

Back

SCRAM

AWS IAM