Enterprise Authentication Mechanisms

Overview

In this guide, you can learn how to authenticate with MongoDB using the authentication mechanisms available only in the MongoDB Enterprise Edition. Authentication mechanisms are processes by which the driver and server confirm the identity of a client to ensure security before connecting.

You can use the following authentication mechanisms with the latest version of MongoDB Enterprise Edition.

• GSSAPI/Kerberos

• LDAP (Plain)

• MONGODB-OIDC

To authenticate using another mechanism, see the Authentication Mechanisms fundamentals page. For more information on establishing a connection to your MongoDB cluster, see the Connection Guide.

You can specify your authentication mechanism and credentials when connecting to MongoDB using either of the following methods:

• A connection string, also known as a connection URI, which is a string that tells the driver how to connect to a MongoDB deployment and how to behave while connected.

• A factory method for the supported authentication mechanism, contained in the MongoCredential class.

Authenticate with GSSAPI/Kerberos

The Generic Security Services API (GSSAPI) authentication mechanism allows the user to authenticate to a Kerberos service using the user's principal name.

The following examples specify the authentication mechanism using the following placeholders:

• <username>: Your URL-encoded principal name; for example "username%40REALM.ME"

• <password>: Your Kerberos user's password

• <hostname>: The network address of your MongoDB server, accessible by your client

Select the Connection String or MongoCredential tab to see the corresponding syntax for specifying the GSSAPI/Kerberos authentication mechanism:

var mongoClient = new MongoClient("mongodb://<username>:<password>@<hostname>/?authMechanism=GSSAPI");

var credential = MongoCredential.CreateGssapiCredential("<username>", "<password>");
var settings = MongoClientSettings.FromConnectionString("<connection string>");
settings.Credential = credential;
var mongoClient = new MongoClient(settings);

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>/?authMechanism=GSSAPI&authMechanismProperties=CANONICALIZE_HOSTNAME:true");

var credential = MongoCredential.CreateGssapiCredential("<db_username>", "<db_passwordpassword>");
credential = credential.WithMechanismProperty("CANONICALIZE_HOST_NAME", "true");
var settings = MongoClientSettings.FromConnectionString("<connection string>");
settings.Credential = credential;
var mongoClient = new MongoClient(settings);

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_REALM:<user's realm>");

var credential = MongoCredential.CreateGssapiCredential("<db_username>", "<db_password>");
credential = credential.WithMechanismProperty("SERVICE_REALM", "<user's realm>");
var settings = MongoClientSettings.FromConnectionString("<connection string>");
settings.Credential = credential;
var mongoClient = new MongoClient(settings);

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:<service name>");

var credential = MongoCredential.CreateGssapiCredential("<db_username>", "<db_password>");
credential = credential.WithMechanismProperty("SERVICE_NAME", "<service name>");
var settings = MongoClientSettings.FromConnectionString("<connection string>");
settings.Credential = credential;
var mongoClient = new MongoClient(settings);

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:<service name>,SERVICE_REALM:<user's realm>");

var credential = MongoCredential.CreateGssapiCredential("<db_username>", "<db_password>");
credential = credential.WithMechanismProperty("SERVICE_REALM", "<user's realm>")
    .WithMechanismProperty("SERVICE_NAME", "<service name>");
var settings = MongoClientSettings.FromConnectionString("<connection string>");
settings.Credential = credential;
var mongoClient = new MongoClient(settings);

Authenticate with LDAP (PLAIN)

You can authenticate to a Lightweight Directory Access Protocol (LDAP) server using your directory-server username and password.

The following examples specify the authentication mechanism using the following placeholders:

• <username>: Your LDAP username

• <password>: Your LDAP password

• <hostname>: The network address of your MongoDB server, accessible by your client

• <authenticationDb>: The MongoDB database that contains your user's authentication

Select the Connection String or MongoCredential tab to see the corresponding syntax for specifying the LDAP authentication mechanism:

var mongoClient = new MongoClient("mongodb://<username>:<password>@<hostname>/?authSource=<authenticationDb>&authMechanism=PLAIN");

var credential = MongoCredential.CreatePlainCredential("<authenticationDb>", "<username>", "<password>");
var settings = MongoClientSettings.FromConnectionString("<connection string>");
settings.Credential = credential;
var mongoClient = new MongoClient(settings);

MONGODB-OIDC

The following sections describe how to use the MONGODB-OIDC authentication mechanism to authenticate from various platforms.

For more information about the MONGODB-OIDC authentication mechanism, see OpenID Connect Authentication and MongoDB Server Parameters in the MongoDB Server manual.

var connectionString = "mongodb://<db_username>@<hostname>[:<port>]/?" +
   "authMechanism=MONGODB-OIDC" +
   "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
var client = new MongoClient(mongoClientSettings);

var mongoClientSettings = MongoClientSettings.FromConnectionString(
   "mongodb+srv://<hostname>[:<port>]");
mongoClientSettings.Credential = MongoCredential.CreateOidcCredential("azure", "<db_username>")
   .WithMechanismProperty("TOKEN_RESOURCE", "<audience>");
var client = new MongoClient(mongoClientSettings);

var connectionString = "mongodb://<hostname>[:<port>]/?" +
   "authMechanism=MONGODB-OIDC" +
   "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>");
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
var client = new MongoClient(mongoClientSettings);

var mongoClientSettings = MongoClientSettings.FromConnectionString(
   "mongodb+srv://<hostname>[:<port>]");
mongoClientSettings.Credential = MongoCredential.CreateOidcCredential("gcp")
   .WithMechanismProperty("TOKEN_RESOURCE", "<audience>");
var client = new MongoClient(mongoClientSettings);

public class MyCallback : IOidcCallback
{
    public OidcAccessToken GetOidcAccessToken(
        OidcCallbackParameters parameters,
        CancellationToken cancellationToken)
    {
        var accessToken = File.ReadAllText("access-token.dat");
        return new(accessToken, expiresIn: null);
    }
    public async Task<OidcAccessToken> GetOidcAccessTokenAsync(
        OidcCallbackParameters parameters,
        CancellationToken cancellationToken)
    {
        var accessToken = await File.ReadAllTextAsync(
            "access-token.dat",
            cancellationToken)
            .ConfigureAwait(false);
        return new(accessToken, expiresIn: null);
    }
}

var mongoClientSettings = MongoClientSettings.FromConnectionString("mongodb://<hostname>[:port]");
mongoClientSettings.Credential = MongoCredential.CreateOidcCredential(new MyCallback());
var client = new MongoClient(mongoClientSettings);

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API Documentation:

• MongoCredential()

• MongoClient()

• MongoClientSettings

• CreateGssapiCredential()

• CreatePlainCredential()

• IOidcCallback