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 username and password, encrypted with the SHA-256 algorithm

  • SCRAM-SHA-1: an authentication mechanism that uses your 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:

  • username: Your username

  • password: Your 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("<username>".to_string())
.password("<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:

  • username: Your username

  • password: Your 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("<username>".to_string())
.password("<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:

  • username: Your username

  • password: Your 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("<username>".to_string())
.password("<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 = "2.8.2"
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.

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:

← Stable API