AWS Identity and Access Management

Overview

The MONGODB-AWS authentication mechanism uses your Amazon Web Services Identity and Access Management (AWS IAM) credentials to authenticate your user. To learn more about configuring MongoDB Atlas, see the Set Up Passwordless Authentication with AWS IAM Roles guide.

To instruct the driver to use this authentication mechanism, you can specify MONGODB-AWS as a parameter in the connection string or by using the MongoCredential.createAwsCredential() factory method.

AWS SDK

You can use one of the AWS SDK for Java v1 or v2 to specify your credentials. This method 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:

1. Specify the authentication mechanism

2. Add the SDK as a dependency to your project

3. Supply your credentials 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:

val credential = MongoCredential.createAwsCredential(null, null)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder: ClusterSettings.Builder ->
        builder.hosts(
            listOf(ServerAddress("<atlasUri>"))
        )
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

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

val mongoClient =
    MongoClient.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.

Specify Your Credentials in the Environment

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:

1. Specify the authentication mechanism

2. Add the appropriate environment variables

You can specify the authentication mechanism by using a MongoCredential or on 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:

val credential = MongoCredential.createAwsCredential(null, null)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder: ClusterSettings.Builder ->
        builder.hosts(
            listOf(ServerAddress("<atlasUri>"))
        )
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

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

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

The next examples show how to provide your credentials by setting environment variables for the following types of authentication:

• Programmatic access keys

• 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.

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 using EC2 container credentials, make sure none of the aforementioned environment variables are set. The driver obtains the credentials from the default IPv4 EC2 instance metadata endpoint.

Specify Your Credentials in a MongoCredential

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 need to supply ECS or EC2 container credentials, use the instructions in Specify Your Credentials in the Environment or AWS SDK.

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

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:

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<atlasUri>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

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

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
    .withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>")
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<atlasUri>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

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

val awsFreshCredentialSupplier: Supplier<AwsCredential> = Supplier {
    // Add your code here to fetch new credentials
    // Return the new credentials
    AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>")
}
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
    .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder ->
        builder.hosts(listOf(ServerAddress("<hostname>", "<port>")))
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

If you must provide AWS IAM credentials in a connection string, you can add it to your MongoClientSettings by calling the applyConnectionString() method:

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
val connectionString = ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>")
val settings = MongoClientSettings.builder()
    .applyConnectionString(connectionString)
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)