Enterprise Authentication Mechanisms

On this page

Kerberos (GSSAPI/SSPI)

LDAP (PLAIN)

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of the Node.js driver.

In this guide, you can find sample code for connection to MongoDB with each authentication mechanism available in the MongoDB Enterprise Edition: Kerberos (GSSAPI/SSPI) and LDAP (PLAIN).

`Kerberos (GSSAPI/SSPI)`

Note

The Node.js driver supports Kerberos on UNIX using the MIT Kerberos library and on Windows using the SSPI API.

The GSSAPI authentication mechanism uses your user principal to authenticate to a Kerberos service.

You can specify this authentication mechanism by performing the following actions while specifying options on your connection string:

Set the authMechanism parameter to GSSAPI.
Set the SERVICE_NAME value in the authMechanismProperties parameter if using a value other than mongodb.
Specify a SERVICE_REALM value in the authMechanismProperties parameter if a custom service realm is required.
Specify a CANONICALIZE_HOST_NAME value in the authMechanismProperties parameter if canonicalization of the hostname is required. This property can take the following values:
- none: (Default) Does not perform hostname canonicalization
- forward: Performs a forward DNS lookup to canonicalize the hostname
- forwardAndReverse: Performs a forward DNS lookup and then a reverse lookup on that value to canonicalize the hostname

Important

The gssapiServiceName parameter is deprecated and may be removed in future versions of the driver. Use authMechanismProperties=SERVICE_NAME:<your service name> in the connection URI instead. See the authMechanismProperties parameter documentation for more information.

The following code sample authenticates to Kerberos for UNIX using GSSAPI.

Important

Always URI encode the principal using the encodeURIComponent method to ensure it is correctly parsed.

const { MongoClient } = require("mongodb");
// specify the placeholder values for your environment in the following lines
const clusterUrl = "<MongoDB cluster URL>";
const principal = encodeURIComponent("<Kerberos principal and realm>");
const serviceRealm = "<Kerberos service realm>";
const canonicalizationSetting = "<canonicalization setting>";
const authMechanismProperties = `SERVICE_REALM:${serviceRealm},CANONICALIZE_HOST_NAME:${canonicalizationSetting}`;
const authMechanism = "GSSAPI";
// Connection URI
const uri = `mongodb+srv://${principal}@${clusterUrl}/?authMechanism=${authMechanism}&authMechanismProperties=${authMechanismProperties}`;
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);

Note

The method refers to the GSSAPI authentication mechanism instead of Kerberos because the driver authenticates via GSSAPI RFC-4652 the SASL mechanism.

`LDAP (PLAIN)`

The PLAIN authentication mechanism uses your username and password to authenticate to a Lightweight Directory Access Protocol (LDAP) server.

You can specify this authentication mechanism by setting the authMechanism parameter to PLAIN and including your LDAP username and password in the connection string as shown in the following sample code.

const { MongoClient } = require("mongodb");
// specify the placeholder values for your environment in the following lines
const clusterUrl = "<MongoDB cluster URL>";
const ldapUsername = "<LDAP username>";
const ldapPassword = "<LDAP password>";
const authMechanism = "PLAIN";
// Connection URI
const uri = `mongodb+srv://${ldapUsername}:${ldapPassword}@${clusterUrl}/?authMechanism=${authMechanism}`;
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);

Note

The authentication mechanism is named PLAIN instead of LDAP since it authenticates using the PLAIN Simple Authentication and Security Layer (SASL) defined in RFC-4616.

Back

Authentication Mechanisms

CRUD Operations