Authentication Mechanisms

On this page

Overview

SCRAM-SHA-256
SCRAM-SHA-1
MONGODB X.509
MONGODB-AWS
Connection URI
Environment Variables
AssumeRoleWithWebIdentity Request
ECS Metadata
EC2 Instance Metadata
API Documentation

Overview

This guide describes the mechanisms you can use in the C++ driver to authenticate users.

SCRAM-SHA-256

SCRAM-SHA-256, as defined by RFC 7677, is the default authentication mechanism on MongoDB deployments running MongoDB v4.0 or later.

To authenticate with this mechanism, set the following connection options:

db_username: The database username to authenticate.
db_password: The database password to authenticate.
authSource: The MongoDB database to authenticate against. By default, C++ driver authenticates against the database in the connection URI, if you include one. If you don't, it authenticates against the admin database.
authMechanism: Set to "SCRAM-SHA-256".

You can set these options in the connection string when creating a mongocxx::client object, as shown in the following example:

auto uri = mongocxx::uri("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
                         "authSource=admin&authMechanism=SCRAM-SHA-256");
auto client = mongocxx::client(uri);

SCRAM-SHA-1

SCRAM-SHA-1, as defined by RFC 5802, is the default authentication mechanism on MongoDB deployments running MongoDB v3.6.

To authenticate with this mechanism, set the following connection options:

db_username: The username to authenticate.
db_password: The password to authenticate.
authSource: The MongoDB database to authenticate against. By default, C++ driver authenticates against the admin database.
authMechanism: Set to "SCRAM-SHA-1".

You can set these options in the connection string when creating a mongocxx::client object, as shown in the following example:

auto uri = mongocxx::uri("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
                         "authSource=admin&authMechanism=SCRAM-SHA-1");
auto client = mongocxx::client(uri);

MONGODB X.509

If you enable TLS, during the TLS handshake, the C++ driver can present an X.509 client certificate to MongoDB to prove its identity. The MONGODB-X509 authentication mechanism uses this certificate to authenticate the client.

To authenticate with this mechanism, set the following connection options:

tls: Set to True.
tlsCertificateKeyFile: The file path of the .pem file that contains your client certificate and private key.
authMechanism: Set to "MONGODB-X509".

You can set these options in the connection string when creating a mongocxx::client object, as shown in the following example:

auto uri = mongocxx::uri("mongodb://<hostname>:<port>/?"
                         "tls=true&tlsCertificateKeyFile=path/to/client.pem&authMechanism=MONGODB-X509");
auto client = mongocxx::client(uri);

To learn more about enabling TLS, see Configure Transport Layer Security (TLS).

MONGODB-AWS

Important

The MONGODB-AWS authentication mechanism requires MongoDB v4.4 or later.

The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and Access Management) or AWS Lambda credentials to authenticate your application. To authenticate using this mechanism, first create a user with an associated Amazon Resource Name (ARN) on the $external database, then specify the MONGODB-AWS authMechanism in the URI.

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

Named parameters passed to the Connection URI
Environment variables
AWS EKS AssumeRoleWithWebIdentity request
ECS container metadata
EC2 instance metadata

The following sections describe how to use the C++ driver to retrieve credentials from these sources and use them to authenticate your application.

Connection URI

First, the C++ driver checks whether you passed AWS credentials to the MongoClient constructor as part of the connection URI. To pass your credentials in the connection URI, set the following connection options:

username: The AWS IAM access key ID to authenticate.
password: The AWS IAM secret access key.
authMechanism: Set to "MONGODB-AWS".

You can set these options in the connection string when creating a mongocxx::client object, as shown in the following example:

auto uri = mongocxx::uri("mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWS");
auto client = mongocxx::client(uri);

You can also include an AWS session token by passing it into the authMechanismProperties parameter:

auto uri = mongocxx::uri("mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?"
                         "authMechanism=MONGODB-AWSS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");
auto client = mongocxx::client(uri);

Environment Variables

If you don't provide a username and password when you construct your MongoClient object, the C++ driver tries to retrieve AWS credentials from the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN (optional)

To use these environment variables to authenticate your application, first set them to the AWS IAM values needed for authentication, as shown in the following code example:

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", as shown in the following example:

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

AssumeRoleWithWebIdentity Request

If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) identity provider, the C++ driver can make an AssumeRoleWithWebIdentity request to exchange the OIDC token for temporary AWS credentials for your application.

To authenticate with temporary AWS IAM credentials returned by an AssumeRoleWithWebIdentity request, ensure that the AWS config file exists in your environment and is configured with the AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN environment variables. To learn how to create and configure an AWS config file, see Configuration in the AWS documentation.

After you configure your environment for an AssumeRoleWithWebIdentity request, set the authMechanism parameter in your connection URI to "MONGODB-AWS", as shown in the following example:

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

For more information about using an AssumeRoleWithWebIdentity request to authenticate your application, see the following AWS documentation:

ECS Metadata

If your application runs in an Elastic Container Service (ECS) container, the C++ driver can automatically retrieve temporary AWS credentials from an ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, as shown in the following example:

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

After you set the environment variable, set the authMechanism parameter in your connection URI to "MONGODB-AWS", as shown in the following example:

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

EC2 Instance Metadata

The C++ driver can automatically retrieve temporary AWS credentials from an Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from within an EC2 instance, set the authMechanism parameter in your connection URI to "MONGODB-AWS", as shown in the following example:

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

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.

API Documentation

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

mongocxx::client

Back

Security

Enterprise Authentication