Docs Home → Develop Applications → MongoDB Drivers → Java
Authentication Mechanisms
On this page
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 MongoDB deployment 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:
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 MongoClients.create()
method to
instantiate your MongoClient
. Select the Connection String
tab to see 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
. Select the
MongoCredential tab to see 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 version of 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 MongoDB 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:
username
- your MongoDB usernamepassword
- your MongoDB user's passwordhostname
- network address of your MongoDB deployment, accessible by your clientport
- port number of your MongoDB deploymentauthenticationDb
- MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default valueadmin
.
Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:
For more information on the challenge-response (CR) and salted challenge-response authentication mechanisms (SCRAM) that MongoDB supports, see the SCRAM section of the MongoDB 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:
username
- your MongoDB username.password
- your MongoDB user's password.hostname
- network address of your MongoDB deployment, accessible by your client.port
- port number of your MongoDB deployment.authenticationDb
- MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default valueadmin
.
Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:
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:
username
- your MongoDB username.password
- your MongoDB user's password.hostname
- network address of your MongoDB deployment, accessible by your client.port
- port number of your MongoDB deployment.authenticationDb
- MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default valueadmin
.
Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:
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 only available in MongoDB versions 4.4 and later.
The MONGODB-AWS
authentication mechanism uses your Amazon Web Services
Identity and Access Management (AWS IAM) credentials to authenticate your
user.
The following code snippets show how to specify the authentication mechanism, using the following placeholders:
awsKeyId
- value of yourAWS_ACCESS_KEY_ID
.awsSecretKey
- value of yourAWS_SECRET_ACCESS_KEY
.atlasUri
- network address of your MongoDB Atlas instance.awsSessionToken
- value of yourAWS_SESSION_TOKEN
. (optional)
Important
URL-encode Your Credentials
Make sure to URL-encode your credentials to prevent backslash or other
characters from causing parsing errors. The following code example
shows you how to URL-encode a sample string, represented by the placeholder
fieldValue
:
String encodedField = java.net.URLEncoder.encode("<fieldValue>".toString(), "ISO-8859-1");
Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:
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 deployment, accessible by your client.port
- port number of your MongoDB deployment.authenticationDb
- MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default valueadmin
.
Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:
For additional information on configuring your application to use certificates as well as TLS/SSL options, see our TLS/SSL guide.