OIDC (Workload Identity Federation)

Code Placeholders

The code examples on this page use the following placeholders:

• +srv: Include this option in your connection string prefix only if you are connecting to a MongoDB Atlas cluster. To learn more about the +srv option, see Connection String Formats in the MongoDB Server manual.

• <username>: The client ID or application ID of the Azure managed identity or enterprise application, if authenticating against Azure IMDS.

• <hostname>: The network address of your MongoDB deployment.

• <port>: The port number of your MongoDB deployment. If you omit this parameter, the driver uses the default port number (27017). You don't need to specify a port when connecting to a MongoDB Atlas cluster.

• <audience>: The audience parameter configured on your MongoDB deployment.

To use the code examples on this page, replace these placeholders with your own values.

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.

var connectionString = "mongodb://<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://<hostname>[:<port>]");
mongoClientSettings.Credential = MongoCredential
   .CreateOidcCredential("azure", "<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.

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://<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);