Authentication Mechanisms

On this page

Overview

Specify an Authentication Mechanism
Mechanisms
Default
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
MONGODB-AWS
X.509

Overview

In this guide, you can learn how to authenticate with MongoDB using each authentication mechanism available in the MongoDB Community Edition. Authentication mechanisms are processes by which the driver and server confirm identity and establish trust to ensure security.

The mechanisms that you can use with the latest version of MongoDB Community Edition are as follows:

Default
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
MONGODB-AWS
X.509

To authenticate using Kerberos or LDAP, see the Enterprise Authentication Mechanisms guide.

For more information on establishing a connection to your MongoDB cluster, read our Connection Guide.

Specify an Authentication Mechanism

You can specify your authentication mechanism and credentials when connecting to MongoDB using either of the following:

A connection string
A MongoCredential factory method

A connection string (also known as a connection URI) specifies how to connect and authenticate to your MongoDB cluster.

To authenticate using a connection string, include your settings in your connection string and pass it to the MongoClient.create() method to instantiate your MongoClient. The Connection String tab in each section provides the syntax for authenticating using a connection string.

Alternatively, you can use the MongoCredential class to specify your authentication details. The MongoCredential class contains static factory methods that construct instances containing your authentication mechanism and credentials. When you use the MongoCredential helper class, you need to use the MongoClientSettings.Builder class to configure your connection settings when constructing your MongoClient. The MongoCredential tab in each section provides the syntax for authenticating using a MongoCredential.

For more information on these classes and methods, refer to the following API documentation:

Mechanisms

Default

The default authentication mechanism setting uses one of the following authentication mechanisms depending on what your MongoDB server supports:

SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR

Server versions 3.6 and earlier use MONGODB-CR as the default mechanism. Newer versions of the server use one of the mechanisms for which they advertise support.

The following code snippets show how to specify the authentication mechanism, using the following placeholders:

db_username - your MongoDB database username
db_password - your MongoDB database user's password
hostname - network address of your MongoDB server, accessible by your client
port - port number of your MongoDB server
authenticationDb - MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value admin.

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

To specify the default authentication mechanism using a connection string, omit the mechanism. Your code to instantiate a MongoClient should resemble the following:

val mongoClient =
    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>")

To specify the default authentication mechanism using the MongoCredential class, use the createCredential() method. Your code to instantiate a MongoClient should resemble the following:

val credential = MongoCredential.createCredential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", "<port>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

For more information on the challenge-response (CR) and salted challenge-response authentication mechanisms (SCRAM) that MongoDB supports, see the SCRAM section of the Server manual.

`SCRAM-SHA-256`

Note

SCRAM-SHA-256 is the default authentication method for MongoDB starting in MongoDB 4.0.

SCRAM-SHA-256 is a salted challenge-response authentication mechanism (SCRAM) that uses your username and password, encrypted with the SHA-256 algorithm, to authenticate your user.

The following code snippets show how to specify the authentication mechanism, using the following placeholders:

db_username - your MongoDB database username.
db_password - your MongoDB database user's password.
hostname - network address of your MongoDB server, accessible by your client.
port - port number of your MongoDB server.
authenticationDb - MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value admin.

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

To specify the SCRAM-SHA-256 authentication mechanism using a connection string, assign the authMechanism parameter the value SCRAM-SHA-256 in your connection string. Your code to instantiate a MongoClient should resemble the following:

val mongoClient =
    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-256")

To specify the default authentication mechanism using the MongoCredential class, use the createScramSha256Credential() method. Your code to instantiate a MongoClient should resemble the following:

val credential = MongoCredential.createScramSha256Credential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", "<port>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

`SCRAM-SHA-1`

Note

SCRAM-SHA-1 is the default authentication method for MongoDB versions 3.0, 3.2, 3.4, and 3.6.

SCRAM-SHA-1 is a salted challenge-response mechanism (SCRAM) that uses your username and password, encrypted with the SHA-1 algorithm, to authenticate your user.

The following code snippets show how to specify the authentication mechanism, using the following placeholders:

db_username - your MongoDB database username.
db_password - your MongoDB database user's password.
hostname - network address of your MongoDB server, accessible by your client.
port - port number of your MongoDB server.
authenticationDb - MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value admin.

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

To specify the SCRAM-SHA-1 authentication mechanism using a connection string, assign the authMechanism parameter the value SCRAM-SHA-1 in your connection string. Your code to instantiate a MongoClient should resemble the following:

val mongoClient =
    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-1")

To specify the default authentication mechanism using the MongoCredential class, use the createScramSha1Credential() method. Your code to instantiate a MongoClient should resemble the following:

val credential = MongoCredential.createScramSha1Credential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", "<port>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

`MONGODB-CR`

MONGODB-CR is a challenge-response authentication mechanism that uses your username and password to authenticate your user. This authentication mechanism was deprecated starting in MongoDB 3.6 and is no longer supported as of MongoDB 4.0.

You cannot specify this method explicitly; refer to the fallback provided by the default authentication mechanism to connect using MONGODB-CR.

`MONGODB-AWS`

Note

The MONGODB-AWS authentication mechanism is available for MongoDB deployments on MongoDB Atlas.

The MONGODB-AWS authentication mechanism uses your Amazon Web Services Identity and Access Management (AWS IAM) credentials to authenticate your user. To learn more about configuring MongoDB Atlas, see the Set Up Passwordless Authentication with AWS IAM Roles guide.

To instruct the driver to use this authentication mechanism, you can specify MONGODB-AWS either as a parameter in the connection string or by using the MongoCredential.createAwsCredential() factory method.

Learn how to specify this authentication mechanism and the various ways to provide your AWS IAM credentials in the next sections.

These sections contain code examples that use the following placeholders:

awsKeyId - value of your AWS access key ID
awsSecretKey - value of your AWS secret access key
atlasUri - network address of your MongoDB Atlas deployment
hostname - hostname of your MongoDB Atlas deployment
port - port of your MongoDB Atlas deployment
awsSessionToken - value of your AWS session token

AWS SDK

You can use one of the AWS SDK for Java v1 or v2 to specify your credentials. This method offers the following features:

Multiple options for obtaining credentials
Credential caching which helps your application avoid rate limiting
Credential provider management for use with the Elastic Kubernetes Service.

To use the AWS SDK for Java for MONGODB-AWS authentication, you must perform the following:

Specify the authentication mechanism
Add the SDK as a dependency to your project
Supply your credentials using one of the methods in the credential provider chain

To specify the authentication mechanism by using a MongoCredential, use the MongoCredential.createAwsCredential() factory method and add the MongoCredential instance to your MongoClient as shown in the following example:

val credential = MongoCredential.createAwsCredential(null, null)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder: ClusterSettings.Builder ->
        builder.hosts(
            listOf(ServerAddress("<atlasUri>"))
        )
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

To specify the authentication mechanism in the connection string, add it as a parameter as shown in the following example:

val mongoClient =
    MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")

To add the AWS SDK as a dependency to your project, see the following AWS documentation for the version you need:

For the AWS SDK for Java v2, see the Setting Up guide.
For the AWS SDK for Java v1, see the Getting Started guide.

Note

For the AWS SDK for Java v2, the Java driver currently tests using the software.amazon.awssdk:auth:2.18.9 dependency.

For the AWS SDK for Java v1, the Java driver currently tests using the com.amazonaws:aws-java-sdk-core:1.12.337 dependency.

To supply your credentials, see the following AWS documentation for the version you need:

To learn more about the AWS SDK for Java v2 class the driver uses to get the credentials, see the DefaultCredentialsProvider API documentation.
Learn how to supply your credentials to this class from the Use the default credential provider chain section.
To learn more about the AWS SDK for Java v1 class the driver uses to get the credentials, see the DefaultAWSCredentialsProviderChain API documentation.
Learn how to supply your credentials to this class from the Using the Default Credential Provider Chain section.

Note

If you include both v1 and v2 of the AWS SDK for Java in your project, you must use the v2 methods to supply your credentials.

Specify Your Credentials in the Environment

You can provide your AWS IAM credentials by instructing the driver to use the MONGODB-AWS authentication mechanism and by setting the appropriate environment variables.

To use the environment variables to supply your credentials, you must perform the following:

Specify the authentication mechanism
Add the appropriate environment variables

You can specify the authentication mechanism by using a MongoCredential or on the connection string.

val credential = MongoCredential.createAwsCredential(null, null)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder: ClusterSettings.Builder ->
        builder.hosts(
            listOf(ServerAddress("<atlasUri>"))
        )
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

To specify the authentication mechanism in the connection string, add it as a parameter as shown in the following example:

val mongoClient =
    MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")

The next examples show how to provide your credentials by setting environment variables for the following types of authentication:

Programmatic access keys
ECS container credentials
EC2 container credentials

The following example shows how you can set your programmatic access keys in environment variables by using bash or a similar shell:

export AWS_ACCESS_KEY_ID=<awsKeyId>
export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
export AWS_SESSION_TOKEN=<awsSessionToken>

Omit the line containing AWS_SESSION_TOKEN if you don't need an AWS session token for that role.

To authenticate by using ECS container credentials, set the ECS endpoint relative URI in an environment variable by using bash or a similar shell as shown in the following example:

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<your ECS endpoint>

To authenticate using EC2 container credentials, make sure none of the aforementioned environment variables are set. The driver obtains the credentials from the default IPv4 EC2 instance metadata endpoint.

Specify Your Credentials in a MongoCredential

You can supply your AWS IAM credentials to a MongoClient by using a MongoCredential instance. To construct the MongoCredential instance for MONGODB-AWS authentication, use the createAwsCredential() factory method.

You can supply only programmatic access keys to the MongoCredential.createAwsCredential() method. If you need to supply ECS or EC2 container credentials, use the instructions in Specify Your Credentials in the Environment or AWS SDK.

To use the MongoCredential for MONGODB-AWS authentication, you must perform the following:

Specify the authentication mechanism
Supply the credentials

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<atlasUri>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

If you need to specify an AWS session token, pass it to the withMechanismProperty() method as shown in the following example:

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
    .withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>")
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<atlasUri>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

To refresh your credentials, you can declare a Supplier lambda expression that returns new credentials as shown in the following example:

val awsFreshCredentialSupplier: Supplier<AwsCredential> = Supplier {
    // Add your code here to fetch new credentials
    // Return the new credentials
    AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>")
}
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
    .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder ->
        builder.hosts(listOf(ServerAddress("<hostname>", "<port>")))
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

If you must provide AWS IAM credentials in a connection string, you can add it to your MongoClientSettings by calling the applyConnectionString() method:

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
val connectionString = ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>")
val settings = MongoClientSettings.builder()
    .applyConnectionString(connectionString)
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

`X.509`

The X.509 authentication mechanism uses TLS with X.509 certificates to authenticate your user, identified by the relative distinguished names (RDNs) of your client certificate. When you specify the X.509 authentication mechanism, the server authenticates the connection using the subject name of the client certificate.

The following code snippets show how to specify the authentication mechanism, using the following placeholders:

hostname - network address of your MongoDB server, accessible by your client.
port - port number of your MongoDB server.
authenticationDb - MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value admin.

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

To specify the X.509 authentication mechanism using a connection string, assign the authMechanism parameter the value MONGODB-X509 and enable TLS by assigning the tls parameter a true value. Your code to instantiate a MongoClient should resemble the following:

val mongoClient =
    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-X509&tls=true")

To specify the X.509 authentication mechanism using the MongoCredential class, use the createMongoX509Credential() method. Also, enable TLS by calling the applyToSslSettings() method and setting the enabled property to true in the SslSettings.Builder block. Your code to instantiate a MongoClient should resemble the following:

val credential = MongoCredential.createMongoX509Credential()
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder ->
        builder.hosts(listOf(
            ServerAddress("<hostname>", "<port>"))
        )
    }
    .applyToSslSettings { builder ->
        builder.enabled(true)
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

For additional information on configuring your application to use certificates as well as TLS/SSL options, see our TLS/SSL guide.

Back

Connect to MongoDB by Using a SOCKS5 Proxy

Enterprise Authentication Mechanisms