OIDC (Workload Identity Federation)

Code Placeholders

The code examples on this page use the following placeholders:

• <db_username>: The MongoDB username of the user to authenticate.

• <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.

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 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://<db_username>@<hostname>:<port>/?" +
   "?authMechanism=MONGODB-OIDC" +
   "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");

MongoCredential credential = MongoCredential.createOidcCredential("<db_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 Java 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(null)
   .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 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());

Custom Callback

The Java 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 uses an example callback to retrieve 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());