Authentication

The Node.js driver supports all MongoDB authentication mechanisms, including those only available in the MongoDB Enterprise Edition.

DEFAULT

To use the default mechanism, either omit the authentication mechanism specification or specify DEFAULT as the mechanism in the URI ConnectionString. The driver will attempt to authenticate using the SCRAM-SHA-1 authentication method if it is available on the MongoDB server. If the server does not support SCRAM-SHA-1, the driver will authenticate using MONGODB-CR.

Include the name and password and the authentication database (authSource) in the connection string.

In the following example, the connection string specifies the user dave, password abc123, and authentication mechanism DEFAULT.

const MongoClient = require('mongodb').MongoClient;
const assert = require('assert');

const user = encodeURIComponent('dave');
const password = encodeURIComponent('abc123');
const authMechanism = 'DEFAULT';

// Connection URL
const url = `mongodb://${user}:${password}@localhost:27017/?authMechanism=${authMechanism}`;

// Create a new MongoClient
const client = new MongoClient(url);

// Use connect method to connect to the Server
client.connect(function(err) {
  assert.equal(null, err);
  console.log("Connected correctly to server");

  client.close();
});

SCRAM-SHA-1

To explicitly connect to MongoDB using SCRAM-SHA-1, specify SCRAM-SHA-1 as the mechanism in the URI connection string.

Include the name and password and the authentication database (authSource) in the connection string.

In the following example, the connection string specifies the user dave, password abc123, authentication mechanism SCRAM-SHA-1, and authentication database myprojectdb

const MongoClient = require('mongodb').MongoClient;
const assert = require('assert');

// Connection URL
const url = 'mongodb://dave:abc123@localhost:27017/?authMechanism=SCRAM-SHA-1&authSource=myprojectdb';

// Create a new MongoClient
const client = new MongoClient(url);

// Use connect method to connect to the Server
client.connect(function(err) {
  assert.equal(null, err);
  console.log("Connected correctly to server");

  client.close();
});

MONGODB-CR

To explicitly connect to MongoDB using MONGODB-CR, specify MONGODB-CR as the mechanism in the URI connection string.

Include the name and password and the authentication database (authSource) in the connection string.

In the following example, the connection string specifies the user dave, password abc123, authentication mechanism MONGODB-CR, and authentication database myprojectdb.

const MongoClient = require('mongodb').MongoClient;
const assert = require('assert');

// Connection URL
const url = 'mongodb://dave:abc123@localhost:27017/?authMechanism=MONGODB-CR&authSource=myprojectdb';

// Create a new MongoClient
const client = new MongoClient(url);

// Use connect method to connect to the Server
client.connect(function(err) {
  assert.equal(null, err);
  console.log("Connected correctly to server");

  client.close();
});

X509

With X.509 mechanism, MongoDB uses the X.509 certificate presented during SSL negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.

X.509 authentication requires the use of SSL connections with certificate validation and is available in MongoDB 2.6 and newer.

To connect using the X.509 authentication mechanism, specify MONGODB-X509 as the mechanism in the URI connection string, ssl=true, and the username. Use enodeURIComponent to encode the username string.

In addition to the connection string, pass to the new MongoClient a connections options for the server with the X.509 certificate and other TLS/SSL connections options.

const MongoClient = require('mongodb').MongoClient;
const assert = require('assert');

// Read the cert and key
const cert = fs.readFileSync(__dirname + "/ssl/x509/client.pem");
const key = fs.readFileSync(__dirname + "/ssl/x509/client.pem");

// User name
const userName = encodeURIComponent("CN=client,OU=kerneluser,O=10Gen,L=New York City,ST=New York,C=US");
const url = `mongodb://${userName}:${password}@server:27017?authMechanism=MONGODB-X509&ssl=true`;

// Create a new MongoClient
const client = new MongoClient(url, {
  sslKey: key,
  sslCert: cert,
  sslValidate: false
});

// Use connect method to connect to the Server
client.connect(function(err) {
  assert.equal(null, err);
  console.log("Connected correctly to server");

  client.close();
});

For more information on connecting to MongoDB instance, replica set, and sharded cluster with TLS/SSL options, see TLS/SSL connections options.

For more information, refer to the MongoDB manual X.509 tutorial for more information about determining the subject name from the certificate.

Kerberos (GSSAPI/SSPI)

MongoDB Enterprise supports proxy authentication through a Kerberos service. The Node.js driver supports Kerberos on UNIX via the MIT Kerberos library and on Windows via the SSPI API.

To connect using the GSSAPI authentication mechanism, specify authMechanism=GSSAPI as the mechanism in the URI connection string. Specify the user principal and the service name in the connection string. Use enodeURIComponent to encode the user principal string.

The following example connects to MongoDB using Kerberos for UNIX.

const MongoClient = require('mongodb').MongoClient;
const assert = require('assert');

// KDC Server
const server = "mongo-server.example.com";
const principal = "drivers@KERBEROS.EXAMPLE.COM";
const urlEncodedPrincipal = encodeURIComponent(principal);

const url = `mongodb://${urlEncodedPrincipal}@${server}/?authMechanism=GSSAPI&gssapiServiceName=mongodb`;

const client = new MongoClient(url);

// Let's write the actual connection code
client.connect(function(err) {
  assert.equal(null, err);

  client.close();
});

LDAP (PLAIN)

MongoDB Enterprise supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service.

To connect using the LDAP authentication mechanism, specify authMechanism=PLAIN as the mechanism in the URI connection string.

const MongoClient = require('mongodb').MongoClient;
const assert = require('assert');

// LDAP Server
const server = "ldap.example.com";
const user = "ldap-user";
const pass = "ldap-password";

// Url
const url = `mongodb://${user}:${pass}@${server}?authMechanism=PLAIN&maxPoolSize=1`;

// Client
const client = new MongoClient(url);

// Let's write the actual connection code
client.connect(function(err) {
  assert.equal(null, err);

  client.close();
});