/ /

Authentication

Docs Home

/ /

Kotlin Coroutine Driver

Kotlin Coroutine Driver

Authentication

OIDC (Workload Identity Federation)

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.

Tip

OIDC Authentication

To learn more about configuring MongoDB Atlas for OIDC authentication, see Set up Workforce Identity Federation with OIDC in the Atlas documentation.

For more information about using OIDC authentication with MongoDB, see OpenID Connect Authentication and MongoDB Server Parameters in the MongoDB server manual.

The following sections describe how to use the MONGODB-OIDC authentication mechanism to authenticate to various platforms.

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

You can specify Azure IMDS OIDC authentication by specifying your credentials in the connection string or by using a MongoCredential instance. Select the Connection String or MongoCredential tab to learn how to specify Azure IMDS OIDC authentication.

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.

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 <OIDC principal> 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 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 driver's built-in GCP support.

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

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())

Kubernetes

If your application runs on a Kubernetes cluster, you can authenticate to MongoDB by using the Kotlin driver's built-in Kubernetes support. You can specify Kubernetes OIDC authentication by specifying your credentials in a connection string or by using a MongoCredential instance.

To specify Kubernetes OIDC as the authentication mechanism, set the following options in your connection string:

authMechanism: Set to MONGODB-OIDC.
authMechanismProperties: Set to ENVIRONMENT:k8s.

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:k8s,TOKEN_RESOURCE:<percent-encoded audience>")
val mongoClient = MongoClient.create(connectionString)

Replace the hostname and port with the network address and port number of your MongoDB deployment. Also, 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", "k8s")
    .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 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 an example 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()
)

Back

AWS IAM

LDAP (PLAIN)