Enterprise Authentication Mechanisms
On this page
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 toGSSAPI
.Set the
SERVICE_NAME
value in theauthMechanismProperties
parameter if using a value other thanmongodb
.Specify a
SERVICE_REALM
value in theauthMechanismProperties
parameter if a custom service realm is required.Specify a
CANONICALIZE_HOST_NAME
value in theauthMechanismProperties
parameter if canonicalization of the hostname is required. This property can take the following values:none
: (Default) Does not perform hostname canonicalizationforward
: Performs a forward DNS lookup to canonicalize the hostnameforwardAndReverse
: 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.