Docs Menu
Docs Home
/ / /
Rust Driver
/

Authentication Mechanisms

On this page

  • Overview
  • SCRAM-Based Mechanisms
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • MONGODB-AWS Mechanism
  • MONGODB-X509 Mechanism
  • Additional Information
  • API Documentation

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.

Tip

To learn how to authenticate to MongoDB by using a Lightweight Directory Access Protocol (LDAP) server, see the guide on Enterprise Authentication Mechanisms.

To learn more about connecting to a MongoDB deployment, see the Connection Guide.

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.

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

Important

Default Authentication Mechanism

If you do not specify an authentication mechanism, the server attempts to validate credentials by using the default authentication mechanism, a SCRAM-based mechanism that varies depending on the version of the server that you are connecting to.

The SCRAM-SHA-256 mechanism is the default authentication mechanism for MongoDB Server versions 4.0 and later.

To use the default authentication mechanism, omit only the mechanism field when you instantiate your Credential struct. This example uses the following placeholders:

  • db_username: Your database username

  • db_password: Your database password

  • db: The authentication database associated with the user

let uri = "<connection string>";
let mut client_options = ClientOptions::parse_async(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)?;

To specify the SCRAM-SHA-256 authentication mechanism, set the mechanism field of your Credential struct to AuthMechanism::ScramSha256. This example specifies the authentication mechanism by using the following placeholders:

  • db_username: Your database username

  • db_password: Your database password

  • db: The authentication database associated with the user

let uri = "<connection string>";
let mut client_options = ClientOptions::parse_async(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)?;

To specify the SCRAM-SHA-1 authentication mechanism, set the mechanism field of your Credential struct to AuthMechanism::ScramSha1. This example specifies the authentication mechanism by using the following placeholders:

  • db_username: Your database username

  • db_password: Your database password

  • db: The authentication database associated with the user

let uri = "<connection string>";
let mut client_options = ClientOptions::parse_async(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)?;

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", ... ]

Important

To use the MONGODB-AWS authentication mechanism in the Rust driver, your application must meet the following requirements:

  • You are connected to MongoDB Server version 4.4 or later.

  • You are using the tokio asynchronous runtime.

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.

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

  • access key ID: Your AWS access key ID

  • secret access key: Your AWS secret access key

  • db: The authentication database associated with the user

If you are using temporary credentials, create a document that contains the value of your AWS session token, and then set the mechanism_properties field of the Credential struct to this document. If you are not using temporary credentials, omit line 9 of the following example:

1let uri = "<connection string>";
2let mut client_options = ClientOptions::parse_async(uri).await?;
3
4let 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
12client_options.credential = Some(aws_cred);
13let client = Client::with_options(client_options)?;

Tip

You can obtain temporary AWS IAM credentials from a Security Token Service (STS) Assume Role request. Learn more about this process in the AssumeRole AWS documentation.

To store your AWS credentials in environment variables, run the following commands in your shell:

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

If you are not using an AWS session token, omit the line that sets the AWS_SESSION_TOKEN environment variable.

Set the mechanism option in your Credential struct to AuthMechanism::MongoDbAws. The driver reads your AWS IAM credentials from your environment variables. The following code shows how to define a Credential struct with AWS authentication specified and connect to MongoDB:

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

You can use the OpenID Connect (OIDC) token obtained from a web identity provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or other services. To use an OIDC token, create a file that contains your token, then define an environment variable whose value is the absolute path to the token file as shown in the following shell command:

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to OIDC token file>

Set the mechanism option in your Credential struct to AuthMechanism::MongoDbAws. The driver reads your AWS IAM credentials from the token file. The following code shows how to define a Credential struct with AWS authentication specified and connect to MongoDB:

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

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_async(uri).await?;
let x509_cred = Credential::builder().mechanism(AuthMechanism::MongoDbAws).build();
client_options.credential = Some(x509_cred);
let client = Client::with_options(client_options)?;

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.

To learn more about the methods and types mentioned in this guide, see the following API documentation:

Back

Stable API