Authentication Mechanisms

Overview

In this guide, you can learn how to use the authentication mechanisms available in the MongoDB Community Edition. When you connect to MongoDB, you can use an authentication mechanism to establish trust between the driver and the server.

This guide describes the following authentication mechanisms:

• SCRAM-Based Mechanisms

• MONGODB-AWS Mechanism

• MONGODB-X509 Mechanism

To select a specific authentication mechanism, you can specify the mechanism, your credentials, and other necessary information in the options of your connection string or in a Credential struct.

In this guide, the examples demonstrate how to configure authentication in a Credential struct.

To learn more about the connection string options for authentication, see the Authentication Options section of the Connection String URI Format guide in the Server manual.

SCRAM-Based Mechanisms

Salted challenge response authentication mechanism (SCRAM) refers to a group of authentication mechanisms that use a username and password to authenticate to a server.

MongoDB supports the following SCRAM-based authentication mechanisms:

• SCRAM-SHA-256: an authentication mechanism that uses your database username and password, encrypted with the SHA-256 algorithm

• SCRAM-SHA-1: an authentication mechanism that uses your database username and password, encrypted with the SHA-1 algorithm

let uri = "<connection string>";
let mut client_options = ClientOptions::parse(uri).await?;
let default_cred = Credential::builder()
    .username("<db_username>".to_string())
    .password("<db_password>".to_string())
    .source("<db>".to_string())
    .build();
client_options.credential = Some(default_cred);
let client = Client::with_options(client_options)?;

let uri = "<connection string>";
let mut client_options = ClientOptions::parse(uri).await?;
let scram_sha_256_cred = Credential::builder()
    .username("<db_username>".to_string())
    .password("<db_password>".to_string())
    .mechanism(AuthMechanism::ScramSha256)
    .source("<db>".to_string())
    .build();
client_options.credential = Some(scram_sha_256_cred);
let client = Client::with_options(client_options)?;

let uri = "<connection string>";
let mut client_options = ClientOptions::parse(uri).await?;
let scram_sha_1_cred = Credential::builder()
    .username("<db_username>".to_string())
    .password("<db_password>".to_string())
    .mechanism(AuthMechanism::ScramSha1)
    .source("<db>".to_string())
    .build();
client_options.credential = Some(scram_sha_1_cred);
let client = Client::with_options(client_options)?;

MONGODB-AWS Mechanism

The MONGODB-AWS authentication mechanism uses your Amazon Web Services Identity and Access Management (AWS IAM) credentials to authenticate your user.

To use this authentication mechanism, you must add the aws-auth feature flag to your mongodb dependency in your project's Cargo.toml file. The following shows an example of what your mongodb dependency feature list must include to enable the MONGODB-AWS authentication mechanism:

[dependencies.mongodb]
version = "3.1.0"
features = [ "aws-auth", ... ]

The driver obtains the credentials only from the first source in which they are found. The driver checks for your credentials from the following sources in the following order:

1. Credential struct or connection string.

2. Environment variables.

3. Web identity token file.

4. AWS ECS endpoint specified in the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable.

5. AWS EC2 endpoint. For more information, see IAM Roles for Tasks in the AWS documentation.

For example, if you specify your AWS credentials in your connection string, the driver uses those credentials and ignores any that you might have specified in environment variables.

Select from the Credential Struct, Environment Variables, and Web Identity Token File tabs below for code samples that demonstrate how to set your AWS IAM credentials in the corresponding ways.

1
let uri = "<connection string>";
2
let mut client_options = ClientOptions::parse(uri).await?;
3
4
let aws_cred = Credential::builder()
5
    .username("<access key ID>".to_string())
6
    .password("<secret access key>".to_string())
7
    .source("<db>".to_string())
8
    .mechanism(AuthMechanism::MongoDbAws)
9
    .mechanism_properties(doc!("AWS_SESSION_TOKEN": "<session token>"))
10
    .build();
11
12
client_options.credential = Some(aws_cred);
13
let client = Client::with_options(client_options)?;

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

let uri = "<connection string>";
let mut client_options = ClientOptions::parse(uri).await?;
let aws_cred = Credential::builder().mechanism(AuthMechanism::MongoDbAws).build();
client_options.credential = Some(aws_cred);
let client = Client::with_options(client_options)?;

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to OIDC token file>

let uri = "<connection string>";
let mut client_options = ClientOptions::parse(uri).await?;
let aws_cred = Credential::builder().mechanism(AuthMechanism::MongoDbAws).build();
client_options.credential = Some(aws_cred);
let client = Client::with_options(client_options)?;

MONGODB-X509 Mechanism

The MONGODB-X509 authentication mechanism uses Transport Level Security (TLS) with X.509 certificates to authenticate your user, which is identified by the relative distinguished names (RDNs) of your client certificate.

When you specify this authentication mechanism, the server authenticates the connection by reading the following files:

• A certificate authority (CA) file, which contains one or more certificate authorities to trust when making a TLS connection

• A certificate key file, which references the client certificate private key

To specify the MONGODB-X509 authentication mechanism, set the mechanism field of your Credential struct to AuthMechanism::MongoDbX509. This example specifies the authentication mechanism by using the following placeholders:

• path to CA certificate: The filepath for your CA file

• path to private client key: The filepath for your certificate key file

• db: The authentication database associated with the user

The following code shows how to reference your certificates in your connection string, specify the MONGODB-X509 authentication mechanism, and connect to MongoDB:

let uri = format!(
    "mongodb://<hostname>:<port>/?tlsCAFile={tlsCAFile}&tlsCertificateKeyFile={tlsCertificateKeyFile}",
    tlsCAFile = "<path to CA certificate>",
    tlsCertificateKeyFile = "<path to private client key>"
);
let mut client_options = ClientOptions::parse(uri).await?;
let x509_cred = Credential::builder().mechanism(AuthMechanism::MongoDbAws).build();
client_options.credential = Some(x509_cred);
let client = Client::with_options(client_options)?;

Additional Information

To learn more about authenticating to MongoDB, see Authentication in the Server manual.

To learn more about managing users of your MongoDB deployment, see Users in the Server manual.