Enterprise Authentication Mechanisms
On this page
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.
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);
Tip
Omitting the Password
You can omit the password if one of the following are true:
On Windows, the process owner running the application is the same as the user needing authentication.
On Linux, the user has initialized their keytab via
kinit username@REALM.COM
.
Additional Properties
You can specify additional properties with your authentication
mechanism using the connection string or a factory method in the MongoCredential
class.
Fully Qualified Domain Name
The following example shows how to use the DNS server to retrieve the fully qualified domain name of the host:
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);
Realm
The following example shows how to specify the user's realm when it is different from the service's realm:
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);
Service name
The following example shows how to specify the service name when it is not the
default mongodb
:
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);
Multiple properties
The following example shows how to specify multiple authentication mechanism properties:
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);
Tip
The method refers to PLAIN instead of LDAP since it authenticates using the PLAIN Simple Authentication and Security Layer (SASL) defined in RFC-4616.
MONGODB-OIDC
Important
The MONGODB-OIDC authentication mechanism requires MongoDB Server v7.0 or later running on a Linux platform.
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.
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 .NET/C# Driver's built-in Azure support.
You can specify Azure IMDS OIDC authentication on a MongoClientSettings
object either by
using a MongoCredential
object or as part of the connection string. Select the
Connection String or MongoCredential tab to
see the corresponding syntax.
The following code example shows how to specify Azure IMDS OIDC authentication.
Replace the <percent-encoded audience>
placeholder with the percent-encoded
value of the audience
parameter configured on your MongoDB deployment.
You cannot pass values containing the comma (,
) character to the authMechanismProperties
option. You must specify values that contain commas in a MongoCredential
object,
as demonstrated in the MongoCredential tab.
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);
The following code example shows how to specify Azure IMDS OIDC authentication.
Replace the <db_username>
placeholder with the client ID or application ID of the
Azure managed identity or enterprise application. Replace the <audience>
placeholder with the value of the audience
parameter configured on your MongoDB
deployment.
var mongoClientSettings = MongoClientSettings.FromConnectionString( "mongodb+srv://<hostname>[:<port>]"); mongoClientSettings.Credential = MongoCredential.CreateOidcCredential("azure", "<db_username>") .WithMechanismProperty("TOKEN_RESOURCE", "<audience>"); var client = new MongoClient(mongoClientSettings);
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 .NET/C# Driver's built-in GCP support.
You can specify GCP IMDS OIDC authentication on a MongoClientSettings
object either by
using a MongoCredential
object or as part of the connection string. Select the
Connection String or MongoCredential tab to
see the corresponding syntax.
The following code example shows how to specify GCP IMDS OIDC authentication as
part of the authentication string.
Replace the <audience>
placeholder with the
value of the audience
parameter configured on your MongoDB deployment.
You cannot pass values containing the comma (,
) character to the authMechanismProperties
option. You must specify values that contain commas in a MongoCredential
object,
as demonstrated in the MongoCredential tab.
var connectionString = "mongodb://<hostname>[:<port>]/?" + "authMechanism=MONGODB-OIDC" + "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>"); var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString); var client = new MongoClient(mongoClientSettings);
The following code example shows how to specify GCP IMDS OIDC authentication by using
a MongoCredential
object.
Replace the <audience>
placeholder with the value of the audience
parameter configured on your MongoDB
deployment.
var mongoClientSettings = MongoClientSettings.FromConnectionString( "mongodb+srv://<hostname>[:<port>]"); mongoClientSettings.Credential = MongoCredential.CreateOidcCredential("gcp") .WithMechanismProperty("TOKEN_RESOURCE", "<audience>"); var client = new MongoClient(mongoClientSettings);
Custom Callback
The .NET/C# 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 class that implements the IOidcCallback
interface. This interface
contains two methods:
GetOidcAccessToken()
: This method accepts the parameters to the callback method and returns the callback response.GetOidcAccessTokenAsync()
: This method is an asynchronous version of the previous method.
The following code is an example implementation of the IOidcCallback
interface.
In this example, the methods retrieve an OIDC token from a file named "access-token.dat"
in the local file system.
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); } }
After you define a class that contains your custom callback methods, call the
MongoCredential.CreateOidcCredential()
method and pass in a new instance of your
class. Store the result of this method call in the Credential
property of your
MongoClientSettings
object, as shown in the following code example:
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: