AWS Identity and Access Management

Code Placeholders

The code examples on this page use the following placeholders:

• <awsKeyId>: Your AWS access key ID

• <atlasUri>: The network address of your MongoDB Atlas deployment

• <awsSecretKey>: Your AWS secret access key

• <awsSessionToken>: Your AWS session token

• <hostname>: The hostname of your MongoDB Atlas deployment

• <port>: The port of your MongoDB Atlas deployment

To use the code examples on this page, replace these placeholders with your own values.

Use AWS SDK for Java

You can specify your credentials by using v1 or v2 of the AWS SDK for Java, which offers the following features:

• Multiple options for obtaining credentials

• Credential caching which helps your application avoid rate limiting

• Credential provider management for use with the Elastic Kubernetes Service.

To use the AWS SDK for Java for MONGODB-AWS authentication, you must perform the following actions:

1. Specify the authentication mechanism

2. Add the SDK as a dependency to your project

3. Supply your credentials by using one of the methods in the credential provider chain

To specify the authentication mechanism by using a MongoCredential, use the MongoCredential.createAwsCredential() factory method and add the MongoCredential instance to your MongoClient as shown in the following example:

MongoCredential credential = MongoCredential.createAwsCredential(null, null);
// Creates a MongoClient that receives configuration information from a MongoCredential and environment variables
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

To specify the authentication mechanism in the connection string, add it as a parameter as shown in the following example:

MongoClient mongoClient = MongoClients.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS");

To add the AWS SDK as a dependency to your project, see the following AWS documentation for the version you need:

• For the AWS SDK for Java v2, see the Setting Up guide.

• For the AWS SDK for Java v1, see the Getting Started guide.

To supply your credentials, see the following AWS documentation for the version you need:

• To learn more about the AWS SDK for Java v2 class the driver uses to get the credentials, see the DefaultCredentialsProvider API documentation.

  Learn how to supply your credentials to this class from the Use the default credential provider chain section.

• To learn more about the AWS SDK for Java v1 class the driver uses to get the credentials, see the DefaultAWSCredentialsProviderChain API documentation.

  Learn how to supply your credentials to this class from the Using the Default Credential Provider Chain section.

Use Environment Variables

You can provide your AWS IAM credentials by instructing the driver to use the MONGODB-AWS authentication mechanism and by setting the appropriate environment variables.

To use the environment variables to supply your credentials, you must perform the following actions:

1. Specify the authentication mechanism

2. Add the appropriate environment variables

You can specify the authentication mechanism by using a MongoCredential or in the connection string.

To specify the authentication mechanism by using a MongoCredential, use the MongoCredential.createAwsCredential() factory method and add the MongoCredential instance to your MongoClient as shown in the following example:

MongoCredential credential = MongoCredential.createAwsCredential(null, null);
// Creates a MongoClient that receives configuration information from a MongoCredential and environment variables
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

To specify the authentication mechanism in the connection string, add it as a parameter as shown in the following example:

MongoClient mongoClient = MongoClients.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS");

You can also set environment variables to enable the following types of authentication:

• Programmatic access keys

• Web identity provider

• ECS container credentials

• EC2 container credentials

The following example shows how you can set your programmatic access keys in environment variables by using bash or a similar shell:

export AWS_ACCESS_KEY_ID=<awsKeyId>
export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
export AWS_SESSION_TOKEN=<awsSessionToken>

Omit the line containing AWS_SESSION_TOKEN if you don't need an AWS session token for that role.

You can use an OpenID Connect (OIDC)-compatible web identity provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or other services.

To use a web identity provider, create a file that contains your OIDC token. Next, use bash or a similar shell to set an environment variable to the absolute path to this file, as shown in the following example:

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>

To authenticate by using ECS container credentials, set the ECS endpoint relative URI in an environment variable by using bash or a similar shell as shown in the following example:

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<your ECS endpoint>

To authenticate by using EC2 container credentials, make sure none of the environment variables mentioned in this section are set. The driver obtains the credentials from the default IPv4 EC2 instance metadata endpoint instead of from environment variables.

Use a MongoCredential Instance

You can supply your AWS IAM credentials to a MongoClient by using a MongoCredential instance. To construct the MongoCredential instance for MONGODB-AWS authentication, use the createAwsCredential() factory method.

You can supply only programmatic access keys to the MongoCredential.createAwsCredential() method. If you must supply ECS or EC2 container credentials, use the instructions in the Use Environment Variables or Use AWS SDK for Java sections.

To use the MongoCredential for MONGODB-AWS authentication, you must perform the following actions:

1. Specify the authentication mechanism

2. Supply the credentials

To specify the authentication mechanism by using a MongoCredential, use the MongoCredential.createAwsCredential() factory method and add the MongoCredential instance to your MongoClient as shown in the following example:

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray());
// Creates a MongoClient that receives AWS credentials from the MongoCredential instance
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

If you must specify an AWS session token, pass it to the withMechanismProperty() method as shown in the following example:

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()).withMechanismProperty("AWS_SESSION_TOKEN",  "<awsSessionToken>");
 // Creates a MongoClient that receives configuration information from a MongoCredential instance
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

To refresh your credentials, you can declare a Supplier lambda expression that returns new credentials as shown in the following example:

Supplier<AwsCredential> awsFreshCredentialSupplier = () -> {
    // Add your code to fetch new credentials
    return new AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>");
};
// Creates a MongoCredential instance to specify the new AWS credentials
MongoCredential credential = MongoCredential.createAwsCredential(null, null)
        .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier);
// Creates a MongoClient that receives new configuration information from a MongoCredential instance
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
            builder.hosts(Collections.singletonList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());