/ /

/ /

OIDC (Workload Identity Federation)

Overview

Important

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

The Rust driver supports OpenID Connect (OIDC) authentication for workload identities. A workload identity is an identity you assign to a software workload, such as an application, service, script, or container, to authenticate and access other services and resources.

You can use this mechanism only when authenticating to MongoDB Atlas or MongoDB Enterprise Advanced.

To learn more about the MONGODB-OIDC authentication mechanism, 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 Rust driver's built-in Azure support.

You can configure OIDC for Azure IMDS by setting the mechanism field of your Credential struct to AuthMechanism::MongoDbOidc. You must also specify the following values to the Credential struct:

username: If you're using an Azure managed identity, set this to the client ID of the managed identity. If you're using a service principal to represent an enterprise application, set this to the application ID of the service principal.
mechanism_properties: Set the ENVIRONMENT property to azure and the TOKEN_RESOURCE to the value of the audience parameter configured on your MongoDB deployment.

Example

The following code example shows how to set these options when creating a Client:

let credential = Credential::builder()
    .username("<username>".to_owned())
    .mechanism(AuthMechanism::MongoDbOidc)
    .mechanism_properties(
        doc! { "ENVIRONMENT": "azure", "TOKEN_RESOURCE": "<audience>" }
    )
    .build();
client_options.credential = Some(credential);
let client = Client::with_options(client_options)?;
let res = client
    .database("test")
    .collection::<Document>("test")
    .find_one(doc! {})
    .await?;

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

You can configure OIDC for GCP IMDS by setting the mechanism field of your Credential struct to AuthMechanism::MongoDbOidc. Then, specify the authentication mechanism by setting the following values in the mechanism_properties field:

ENVIRONMENT: Set this property to gcp.
TOKEN_RESOURCE: Set this property to the value of the audience parameter configured on your MongoDB deployment.

Example

The following code example shows how to set these options when creating a Client:

let credential = Credential::builder()
    .mechanism(AuthMechanism::MongoDbOidc)
    .mechanism_properties(
        doc! { "ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>" }
    )
    .build();
client_options.credential = Some(credential);
let client = Client::with_options(client_options)?;
let res = client
    .database("test")
    .collection::<Document>("test")
    .find_one(doc! {})
    .await?;

Kubernetes

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

You can configure OIDC for Kubernetes by setting the mechanism field of your Credential struct to AuthMechanism::MongoDbOidc. Then, specify the authentication mechanism by setting the ENVIRONMENT property to k8s in the mechanism_properties field.

The following code example shows how to set these options when creating a Client:

let credential = Credential::builder()
.mechanism(AuthMechanism::MongoDbOidc)
.mechanism_properties(
    doc! { "ENVIRONMENT": "k8s" }
)
.build();
client_options.credential = Some(credential);
let client = Client::with_options(client_options)?;
let res = client
    .database("test")
    .collection::<Document>("test")
    .find_one(doc! {})
    .await?;

Custom Callback

The Rust driver doesn't offer built-in support for all platforms, including the AWS Elastic Kubernetes Service (EKS). To use OIDC to authenticate against unsupported platforms, you must define a custom callback function.

Machine Callback

The following code is an example implementation of a custom callback for an EKS cluster. First, set the oidc_callback field of your Credential struct to oidc::Callback::machine. Then, read the access token from a path set in the AWS_WEB_IDENTITY_TOKEN_FILE environment variable. Finally, set the value of the access_token field of the IdpServerResponse struct. Optionally, set the values of the expires and refresh_token fields.

let credential = Credential::builder()
.mechanism(AuthMechanism::MongoDbOidc)
.oidc_callback(oidc::Callback::machine(move |_| {
    async move {
        let token_file_path = std::env::var("AWS_WEB_IDENTITY_TOKEN_FILE").map_err(mongodb::error::Error::custom)?;
        let access_token = tokio::fs::read_to_string(token_file_path).await?;
        Ok(IdpServerResponse::builder().access_token(access_token).build())
    }
    .boxed()
}))
.build()
.into();
client_options.credential = Some(credential);
let client = Client::with_options(client_options)?;
let res = client
    .database("test")
    .collection::<Document>("test")
    .find_one(doc! {})
    .await?;

Human Callback

When the workforce identity authentication process involves human interaction, you must configure the client by setting the oidc_callback field of your Credential struct to oidc::Callback::human instead of oidc::Callback::machine. The Rust driver uses the callback in the following process:

The driver retrieves the Identity Provider Information (IDPInfo) for the provided username.
The callback negotiates with the IDP to obtain an access_token, and any potential refresh_token and timeout values, if configured. The callback returns a Result<IdpServerInfo>.

The following example defines a custom callback to handle workforce identity. To customize this example for your use case, replace <human flow> with your own custom flow. Refer to Authorization Code Flow with OIDC for more details.

let callback = Callback::human(move |context| {
    async move {
        "<human flow>";
        todo!("human flow")
    }
    .boxed()
});
let credential = Credential::builder()
    .mechanism(AuthMechanism::MongoDbOidc)
    .oidc_callback(callback)
    .build();
client_options.credential = Some(credential);
let client = Client::with_options(client_options)?;
let res = client
    .database("test")
    .collection::<Document>("test")
    .find_one(doc! {})
    .await?;

Additional Information

To learn more about the concepts in this guide, see the following documentation:

Specify Connection Options guide
Connection Strings in the Server manual

API Documentation

To learn more about the methods and types mentioned in this guide, see the following API documentation:

Back

AWS IAM

LDAP (PLAIN)