Enterprise Authentication Mechanisms

Azure IMDS

If your application runs on an Azure VM, or otherwise uses the Azure Instance Metadata Service (IMDS), you can authenticate to MongoDB by using the Node.js driver's built-in Azure support.

To specify Azure IMDS OIDC as the authentication mechanism, set the following options in your connection string:

• username: If you're using an Azure managed identity, set this to the client ID of the managed identity. If you're using a service principal to represent an enterprise application, set this to the application ID of the service principal. Otherwise, omit this option.

• authMechanism: Set to MONGODB-OIDC.

• authMechanismProperties: Set to ENVIRONMENT:azure,TOKEN_RESOURCE:<audience>. Replace the <audience> placeholder with the value of the audience parameter configured on your MongoDB deployment.

The following code example shows how to set the preceding connection options:

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<username>@<hostname>:<port>/?authMechanism=MONGODB-OIDC"
            + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<audience>";
const client = new MongoClient(uri);

GCP IMDS

If your application runs on a Google Compute Engine VM, or otherwise uses the GCP Instance Metadata Service, you can authenticate to MongoDB by using the Node.js driver's built-in GCP support.

To specify GCP IMDS OIDC as the authentication mechanism, set the following options in your connection string:

• authMechanism: Set to MONGODB-OIDC.

• authMechanismProperties: Set to ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>. Replace the <audience> placeholder with the value of the audience parameter configured on your MongoDB deployment.

The following code example shows how to set the preceding connection options:

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC"
            + "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>";
const client = new MongoClient(uri);

Custom Callback

The Node.js driver doesn't offer built-in support for all platforms, including Azure Functions and Azure Kubernetes Service (AKS). Instead, you must define a custom callback to use OIDC to authenticate from these platforms.

First, define a function that retrieves the access token to use for OIDC authentication. This function must have the following signature:

const myCallback = (params: OIDCCallbackParams): Promise<OIDCResponse> => { }

The OIDCCallbackParams parameter contains the following properties, which you can access inside the function:

The callback function must return an OIDCResponse object. This object contains the following properties:

The following example shows a callback function that retrieves an OIDC access token from a file named access-token.dat in the local file system:

const fs = require("node:fs");
const myCallback = (params: OIDCCallbackParams): Promise<OIDCResponse> => {
  const token = fs.readFileSync("access-token.dat", "utf8");
  return {
    accessToken: token,
    expiresInSeconds: 300,
    refreshToken: token
  };
}

After you define your callback function, pass it to the MongoClient constructor as part of the authMechanismProperties parameter. The Node.js driver supports the following authentication patterns:

• Machine authentication: Used by web services and other applications that require no human interaction. Select the Machine Callback tab to see an example of this syntax.

• Human authentication: Used by database tools, command-line utilities, and other applications that involve direct human interaction. Select the Human Callback tab to see an example of this syntax.

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC";
const client = new MongoClient(uri, {
  authMechanismProperties: {
    OIDC_CALLBACK: myCallback
  }
});

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC";
const client = new MongoClient(uri, {
  authMechanismProperties: {
    OIDC_HUMAN_CALLBACK: myCallback
  }
});