Authentication Mechanisms
On this page
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.
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:
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
algorithmSCRAM-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 usernamedb_password
: Your database passworddb
: 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)?;
SCRAM-SHA-256
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 usernamedb_password
: Your database passworddb
: 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)?;
SCRAM-SHA-1
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 usernamedb_password
: Your database passworddb
: 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)?;
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", ... ]
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:
Credential
struct or connection string.Environment variables.
Web identity token file.
AWS ECS endpoint specified in the
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
environment variable.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 IDsecret access key
: Your AWS secret access keydb
: 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:
1 let uri = "<connection string>"; 2 let mut client_options = ClientOptions::parse_async(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)?;
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)?;
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 filepath to private client key
: The filepath for your certificate key filedb
: 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)?;
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.
API Documentation
To learn more about the methods and types mentioned in this guide, see the following API documentation: