OIDC Authentication

Overview

The OpenID Connect (OIDC) authentication mechanism allows you to authenticate to MongoDB by using a third-party identity provider, such as Azure or Google Cloud Platform (GCP).

You can use this mechanism only when authenticating to MongoDB Atlas or MongoDB Enterprise Advanced, and only when authenticating to MongoDB v7.0 or later.

Important

The MONGODB-OIDC authentication mechanism requires MongoDB Server v7.0 or later running on a Linux platform.

Tip

OIDC Authentication

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

Specify OIDC Authentication

The following sections describe how to use OIDC authentication to authenticate from different platforms. The code examples use the following placeholders:

<OIDC principal>: 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.

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 Kotlin Sync driver's built-in Azure support.

You can specify Azure IMDS OIDC authentication either by using a MongoCredential instance or by specifying your credentials in the connection string.

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

Replace the <percent-encoded audience> placeholder in the following code with the percent-encoded value of the audience server parameter configured on your MongoDB deployment.

The comma (,) character and its encoding (%2C) are reserved, and using these characters in a value causes the driver to interpret commas as delimiters of key-value pairs. You must specify values that contain commas in a MongoCredential instance, as demonstrated in the MongoCredential tab.

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

Replace the <audience> placeholder with the value of the audience server parameter configured on your MongoDB deployment.

val credential = MongoCredential.createOidcCredential("<OIDC principal>")
    .withMechanismProperty("ENVIRONMENT", "azure")
    .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
val mongoClient = MongoClient.create(
        MongoClientSettings.builder()
            .applyToClusterSettings { builder ->
                builder.hosts(listOf(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 Kotlin Sync driver's built-in GCP support.

You can specify GCP IMDS OIDC authentication either by using a MongoCredential instance or by specifying your credentials in the connection string.

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

Replace the <percent-encoded audience> placeholder in the following code with the percent-encoded value of the audience server parameter configured on your MongoDB deployment.

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

Replace the <audience> placeholder with the value of the audience server parameter configured on your MongoDB deployment.

val credential = MongoCredential.createOidcCredential("<OIDC principal>")
    .withMechanismProperty("ENVIRONMENT", "gcp")
    .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyToClusterSettings { builder ->
            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
        }
        .credential(credential)
        .build())

Custom Callback

The Kotlin Sync 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:

val credential = MongoCredential.createOidcCredential(null)
    .withMechanismProperty("OIDC_CALLBACK") { context: Context ->
        val accessToken = "..."
        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 a sample callback to retrieve an OIDC token from a file named "access-token.dat" in the local file system:

val credential = MongoCredential.createOidcCredential(null)
    .withMechanismProperty("OIDC_CALLBACK") { context: Context ->
        val accessToken = String(Files.readAllBytes(Paths.get("access-token.dat")))
        OidcCallbackResult(accessToken)
    }
val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyToClusterSettings { builder ->
            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
        }
        .credential(credential)
        .build()
)

Additional Information

To learn more about authenticating to MongoDB, see Authentication in the MongoDB Server manual.

To learn more about creating a MongoClient object by using the Kotlin Sync driver, see the Create a MongoClient guide.

API Documentation

To learn more about the classes and methods for authenticating your application with Kotlin Sync driver, see the following API documentation:

Back

AWS IAM

LDAP (PLAIN)