Authentication Mechanisms
On this page
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 theadmin
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 theadmin
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 toTrue
.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: