/ /

AWS Identity and Access Management

Overview

Note

AWS authentication is available only in the MongoDB Enterprise Edition for MongoDB 4.4 and later.

The MONGODB-AWS authentication mechanism uses AWS Identity and Access Management (IAM) and AWS Security Token Service (STS) to prove the client's identity to a MongoDB deployment. The following steps describe the AWS authentication process:

The client uses AWS IAM credentials to create a signature and sends it to the MongoDB deployment.
The deployment uses the client's signature to send a request to AWS STS.
If the request succeeds, STS returns the Amazon Resource Name (ARN) of the IAM user or role that corresponds to the client's credentials.
The deployment uses the returned ARN to look up the user. The client authenticates as this user.

Note

The client and server use different usernames. The client sends the AWS access key ID as the username. The server uses the ARN of the IAM user or role corresponding to the access key ID as the username.

To authenticate with this mechanism:

Create a user on the $external database whose name is the ARN of the IAM user or role you want to authenticate as.
Configure the client to use the MONGODB-AWS authentication mechanism.

AWS Credentials

AWS credentials include the following components:

Access key ID
Secret access key
Optional session token

Authentication with AWS IAM credentials uses the access key ID and the secret access key. Authentication with temporary AWS IAM credentials uses all three components: access key ID, secret access key, and session token.

Note

The driver never sends the secret access key or the session token over the network.

Temporary credentials are used with:

Code Placeholders

The code examples on this page use the following placeholders:

<hostname>: The network address of your MongoDB deployment.
<port>: The port number of your MongoDB deployment.
<aws_access_key_id>: The AWS access key ID.
<aws_secret_access_key>: The AWS secret access key.
<aws_session_token>: The AWS session token.

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

Using AWS IAM Authentication in Your Application

The C++ driver can retrieve AWS IAM credentials from the environment, or you can provide them explicitly in your application code.

When you use the MONGODB-AWS authentication mechanism, the C++ driver attempts to retrieve AWS credentials from the following sources, in this order:

Credentials passed in the connection URI
Environment variables
AWS EKS AssumeRoleWithWebIdentity request
ECS container metadata
EC2 instance metadata

Providing Credentials Explicitly

You can provide long-term (non-temporary) IAM credentials in the connection URI. To do so, set the following URI parameters:

username: Set to your AWS access key ID.
password: Set to your AWS secret access key.
authMechanism: Set to MONGODB-AWS.

You can use the connection URI by itself or the connection URI with TLS options configured by using the mongocxx::options::tls and mongocxx::options::client classes. Select the Connection URI or Client Options with TLS tab to see the corresponding syntax:

auto uri = mongocxx::uri("mongodb://<aws_access_key_id>:<aws_secret_access_key>@<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS");
auto client = mongocxx::client(uri);

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.ca_file("/path/to/ca.pem");
client_options.tls_opts(tls_options);
auto uri = mongocxx::uri("mongodb://<aws_access_key_id>:<aws_secret_access_key>@<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS&tls=true");
auto client = mongocxx::client(uri, client_options);

Note

If you provide credentials in a URI, percent-encode any special characters in the access key ID or secret access key.

Providing Temporary Credentials

You can provide temporary IAM credentials in the connection URI by including the session token in the authMechanismProperties parameter of the connection URI.

Select the Connection URI or Client Options with TLS tab to see the corresponding syntax:

auto uri = mongocxx::uri("mongodb://<aws_access_key_id>:<aws_secret_access_key>@<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<aws_session_token>");
auto client = mongocxx::client(uri);

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.ca_file("/path/to/ca.pem");
client_options.tls_opts(tls_options);
auto uri = mongocxx::uri("mongodb://<aws_access_key_id>:<aws_secret_access_key>@<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS"
                         "&authMechanismProperties=AWS_SESSION_TOKEN:<aws_session_token>&tls=true");
auto client = mongocxx::client(uri, client_options);

Automatically Retrieving Credentials

When you specify the MONGODB-AWS authentication mechanism and omit the username and password, the C++ driver automatically attempts to retrieve AWS credentials from environment variables, web identity roles, and AWS metadata endpoints.

Environment Variables

The C++ driver first checks for the credentials from the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN (optional)

These variables are recognized by many AWS tools and SDKs, such as the AWS CLI, and are also commonly set in AWS Lambda environments.

Example of setting these variables:

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

After you set these environment variables, set the authMechanism parameter in your connection URI to "MONGODB-AWS". Select the Connection URI or Client Options with TLS tab to see the corresponding syntax:

auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS");
auto client = mongocxx::client(uri);

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.ca_file("/path/to/ca.pem");
client_options.tls_opts(tls_options);
auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS&tls=true");
auto client = mongocxx::client(uri, client_options);

AssumeRoleWithWebIdentity

If your application runs in an Amazon EKS cluster and authenticates through an OpenID Connect (OIDC) identity provider, the C++ driver can use an AssumeRoleWithWebIdentity request. This request exchanges the OIDC token for temporary AWS credentials for your application.

To configure this mechanism:

Create or update your AWS configuration file. To learn how to create this configuration file, see Globally configuring AWS SDKs and tools.
Set the following environment variables:
- AWS_ROLE_ARN: Set to the ARN of the IAM role to assume.
- AWS_WEB_IDENTITY_TOKEN_FILE: Set to the path of the file that contains the OIDC token for your service account.
- AWS_ROLE_SESSION_NAME (optional): Set to an identifier for the assumed role session. If you omit this variable, the driver generates a random identifier.
Set the authMechanism parameter in your connection URI to "MONGODB-AWS".

Select the Connection URI or Client Options with TLS tab to see the corresponding syntax:

auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS");
auto client = mongocxx::client(uri);

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.ca_file("/path/to/ca.pem");
client_options.tls_opts(tls_options);
auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS&tls=true");
auto client = mongocxx::client(uri, client_options);

To learn more about authenticating with web identity roles, see AssumeRoleWithWebIdentity API

ECS Task Metadata

If your application runs in an Amazon ECS container, the C++ driver can retrieve temporary AWS credentials from the ECS task metadata endpoint.

To enable this behavior, set the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable to the relative URI of the ECS task metadata endpoint, as shown in the following example:

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<relative URI of the ECS task metadata endpoint>

Then construct the client with the authMechanism set to "MONGODB-AWS". Select the Connection URI or Client Options with TLS tab to see the corresponding syntax:

auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS");
auto client = mongocxx::client(uri);

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.ca_file("/path/to/ca.pem");
client_options.tls_opts(tls_options);
auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS&tls=true");
auto client = mongocxx::client(uri, client_options);

EC2 Instance Metadata

If your application runs on an Amazon EC2 instance, the C++ driver can retrieve temporary AWS credentials from the EC2 instance metadata endpoint.

To enable this behavior, set the authMechanism parameter in your connection URI to "MONGODB-AWS". Select the Connection URI or Client Options with TLS tab to see the corresponding syntax:

auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS");
auto client = mongocxx::client(uri);

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.ca_file("/path/to/ca.pem");
client_options.tls_opts(tls_options);
auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS&tls=true");
auto client = mongocxx::client(uri, client_options);

Note

If you set any of the environment variables from the preceding AWS authentication methods, the C++ driver attempts to retrieve credentials by using those methods before attempting to retrieve them from an EC2 instance. To attempt to retrieve credentials only from an EC2 instance, ensure that the environment variables are not set.

If an application runs in an ECS container on an EC2 instance and the container is allowed access to the instance metadata, the driver attempts to retrieve AWS credentials from the EC2 instance metadata endpoint. If the driver retrieves credentials in this way, your application can authenticate as the IAM role assigned to the EC2 instance.

To learn how to prevent containers from accessing EC2 instance metadata, see the AWS documentation.

API Documentation

To learn more about creating a mongocxx::client object in the C++ driver or configuring TLS, see the following API documentation:

Back

X.509

Kerberos (GSSAPI)