OIDC (Workload Identity Federation)

Code Placeholders

The code examples on this page use the following placeholders:

• <username>: The client ID or application ID of the Azure managed identity or enterprise application. Used for Azure IMDS authentication.

• <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 a port number when connecting to a MongoDB Atlas cluster.

• <audience> or <percent-encoded audience>: The value of the audience server parameter configured on your MongoDB deployment. Percent-encode this value when specifying it in a connection string.

To use the code examples, 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 Java Reactive Streams driver's built-in Azure support.

You can specify Azure IMDS OIDC authentication either by using a MongoCredential or as part of the connection string.

Select from the Connection String or MongoCredential tabs to see the corresponding syntax:

MongoClient mongoClient = MongoClients.create(
            "mongodb://<username>@<hostname>:<port>/?" + 
            "?authMechanism=MONGODB-OIDC" +
            "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");

MongoCredential credential = MongoCredential.createOidcCredential("<username>")
.withMechanismProperty("ENVIRONMENT", "azure")  
.withMechanismProperty("TOKEN_RESOURCE", "<audience>");
MongoClient mongoClient = MongoClients.create(
 MongoClientSettings.builder()
     .applyToClusterSettings(builder ->
             builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
     .credential(credential)
     .build());

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 Java Reactive Streams driver's built-in GCP support.

You can specify GCP IMDS OIDC authentication either by using a MongoCredential or as part of the connection string.

Select from the Connection String or MongoCredential tabs to see the corresponding syntax:

MongoClient mongoClient = MongoClients.create(
    "mongodb://<hostname>:<port>/?" +
    "authMechanism=MONGODB-OIDC" +
    "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>");

MongoCredential credential = MongoCredential.createOidcCredential()
            .withMechanismProperty("ENVIRONMENT", "gcp")
            .withMechanismProperty("TOKEN_RESOURCE", "<audience>");
   
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

Kubernetes

If your application runs on a Kubernetes cluster, you can authenticate to MongoDB by using the Java Reactive Streams driver's built-in Kubernetes support.

Select from the Connection String or MongoCredential tabs to see the corresponding syntax.

MongoClient mongoClient = MongoClients.create(
   "mongodb://<hostname>:<port>/" +
   "?authMechanism=MONGODB-OIDC" +
   "&authMechanismProperties=ENVIRONMENT:k8s");

MongoCredential credential = MongoCredential.createOidcCredential(null)
   .withMechanismProperty("ENVIRONMENT", "k8s");
MongoClient mongoClient = MongoClients.create(
   MongoClientSettings.builder()
      .applyToClusterSettings(builder ->
             builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
      .credential(credential)
      .build());

If you specify Kubernetes OIDC as the authentication mechanism, the driver reads the contents of the OIDC token from one of the following locations:

• AZURE_FEDERATED_TOKEN_FILE environment variable for applications running on Azure Kubernetes Service (AKS)

• AWS_WEB_IDENTITY_TOKEN_FILE environment variable for applications running on Elastic Kubernetes Service (EKS)

• /var/run/secrets/kubernetes.io/serviceaccount/token file, the default location for all other applications, including ones that run on Google Kubernetes Engine (GKE)

You must store your OIDC token in the location that corresponds to the service you use to run your application.

Custom Callback

The Java Reactive Streams 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. To do so, use the "OIDC_CALLBACK" authentication property, as shown in the following code example:

MongoCredential credential = MongoCredential.createOidcCredential(null)
    .withMechanismProperty("OIDC_CALLBACK", (context) ->  {
       String accessToken = ...
       return new OidcCallbackResult(accessToken);
});

The value of the "OIDC_CALLBACK" property must be a lambda or other implementation of the OidcCallback functional interface that accepts an OidcCallbackContext as a parameter and returns an OidcCallbackResult.

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

MongoCredential credential = MongoCredential.createOidcCredential(null)
      .withMechanismProperty("OIDC_CALLBACK", (context) ->  {
         string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat"));
         return new OidcCallbackResult(accessToken);
      });
   MongoClient mongoClient = MongoClients.create(
       MongoClientSettings.builder()
           .applyToClusterSettings(builder ->
                   builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
           .credential(credential)
           .build());