/ /

/ /

AWS IAM

Overview

The MONGODB-AWS authentication mechanism uses your Amazon Web Services Identity and Access Management (AWS IAM) credentials to authenticate your user.

You can use AWS IAM to authenticate to MongoDB Atlas, but not to MongoDB Enterprise Advanced or MongoDB Community Edition.

Code Placeholders

The code examples on this page use the following placeholders:

access key ID: Your AWS access key ID
secret access key: Your AWS secret access key
session token: Your AWS session token
db: The authentication database associated with the user

Setup

To use this authentication mechanism, you must add the aws-auth feature flag to your mongodb dependency in your project's Cargo.toml file. The following shows an example of what your mongodb dependency feature list must include to enable the MONGODB-AWS authentication mechanism:

[dependencies.mongodb]
version = "3.5.2"
features = [ "aws-auth", ... ]

Important

To use the MONGODB-AWS authentication mechanism in the Rust driver, your application must meet the following requirements:

You are connected to MongoDB Server version 4.4 or later.
You are using the tokio asynchronous runtime.

Credential Sources

The driver obtains the credentials only from the first source in which they are found. The driver checks for your credentials from the following sources in the following order:

Credential struct or connection string.
Environment variables.
Web identity token file.
AWS ECS endpoint specified in the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable.
AWS EC2 endpoint. For more information, see IAM Roles for Tasks in the AWS documentation.

For example, if you specify your AWS credentials in your connection string, the driver uses those credentials and ignores any that you might have specified in environment variables.

Select from the Credential Struct, Environment Variables, and Web Identity Token File tabs below for code samples that demonstrate how to set your AWS IAM credentials in the corresponding ways.

To specify the MONGODB-AWS authentication mechanism, set the mechanism field of your Credential struct to AuthMechanism::MongoDbAws.

If you are using temporary credentials, create a document that contains the value of your AWS session token, and then set the mechanism_properties field of the Credential struct to this document. If you are not using temporary credentials, omit line 9 of the following example:

1 let uri = "<connection string>";
2 let mut client_options = ClientOptions::parse(uri).await?;
3 
4 let aws_cred = Credential::builder()
5     .username("<access key ID>".to_string())
6     .password("<secret access key>".to_string())
7     .source("<db>".to_string())
8     .mechanism(AuthMechanism::MongoDbAws)
9     .mechanism_properties(doc!("AWS_SESSION_TOKEN": "<session token>"))
10     .build();
11 
12 client_options.credential = Some(aws_cred);
13 let client = Client::with_options(client_options)?;

Tip

You can obtain temporary AWS IAM credentials from a Security Token Service (STS) Assume Role request. Learn more about this process in the AssumeRole AWS documentation.

To store your AWS credentials in environment variables, run the following commands in your shell:

export AWS_ACCESS_KEY_ID=<access key ID>
export AWS_SECRET_ACCESS_KEY=<secret access key>
export AWS_SESSION_TOKEN=<session token>

If you are not using an AWS session token, omit the line that sets the AWS_SESSION_TOKEN environment variable.

Set the mechanism option in your Credential struct to AuthMechanism::MongoDbAws. The driver reads your AWS IAM credentials from your environment variables. The following code shows how to define a Credential struct with AWS authentication specified and connect to MongoDB:

let uri = "<connection string>";
let mut client_options = ClientOptions::parse(uri).await?;
let aws_cred = Credential::builder().mechanism(AuthMechanism::MongoDbAws).build();
client_options.credential = Some(aws_cred);
let client = Client::with_options(client_options)?;

You can use the OpenID Connect (OIDC) token obtained from a web identity provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or other services. To use an OIDC token, create a file that contains your token, then define an environment variable whose value is the absolute path to the token file as shown in the following shell command:

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to OIDC token file>

Set the mechanism option in your Credential struct to AuthMechanism::MongoDbAws. The driver reads your AWS IAM credentials from the token file. The following code shows how to define a Credential struct with AWS authentication specified and connect to MongoDB:

let uri = "<connection string>";
let mut client_options = ClientOptions::parse(uri).await?;
let aws_cred = Credential::builder().mechanism(AuthMechanism::MongoDbAws).build();
client_options.credential = Some(aws_cred);
let client = Client::with_options(client_options)?;

Additional Information

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

To learn more about managing users of your MongoDB deployment, see Users in the MongoDB Server manual.

API Documentation

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

Back

X.509

OIDC

1	let uri = "<connection string>";
2	let mut client_options = ClientOptions::parse(uri).await?;
3
4	let aws_cred = Credential::builder()
5	.username("<access key ID>".to_string())
6	.password("<secret access key>".to_string())
7	.source("<db>".to_string())
8	.mechanism(AuthMechanism::MongoDbAws)
9	.mechanism_properties(doc!("AWS_SESSION_TOKEN": "<session token>"))
10	.build();
11
12	client_options.credential = Some(aws_cred);
13	let client = Client::with_options(client_options)?;