- Java Driver
- Tutorials
- Connect to MongoDB
- Authentication
Authentication
The Java driver supports all MongoDB authentication mechanisms, including those only available in the MongoDB Enterprise Edition.
MongoCredential
import com.mongodb.MongoCredential;
New MongoClient API (since 3.7):
import com.mongodb.ConnectionString;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;
Legacy MongoClient API:
import com.mongodb.MongoClient;
import com.mongodb.ConnectionString;
An authentication credential is represented as an instance of the
MongoCredential
class. The MongoCredential
class includes static
factory methods for each of the supported authentication mechanisms.
You can also use a ConnectionString
and pass it to a
MongoClient()
constructor that takes a ConnectionString
parameter.
Default Authentication Mechanism
In MongoDB 3.0, MongoDB changed the default authentication mechanism from MONGODB-CR
to
SCRAM-SHA-1
. In MongoDB 4.0 support for the deprecated
MONGODB-CR
mechanism was removed and
SCRAM-SHA-256
support was added.
To create a credential that will authenticate using the default
authentication mechanism regardless of server version, create a
credential using the createCredential
static factory method:
String user; // the user name
String source; // the source where the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createCredential(user, source, password);
and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string without explicitly specifying the authentication mechanism. Using the new MongoClient API:
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1");
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1");
For challenge and response mechanisms, using the default authentication mechanism is the recommended approach as it will make upgrading from MongoDB 2.6 to MongoDB 3.0 seamless, even after upgrading the authentication schema. For MongoDB 4.0 users it is also recommended as the supported authentication mechanisms are checked and the correct hashing algorithm is used.
SCRAM
Salted Challenge Response Authentication Mechanism (SCRAM
) has been the default authentication mechanism for MongoDB since 3.0. SCRAM
is
based on the IETF RFC 5802 standard that defines best practices for implementation of
challenge-response mechanisms for authenticating users with passwords.
MongoDB 3.0 introduced support for SCRAM-SHA-1
which uses the SHA-1
hashing function. MongoDB 4.0 introduced support for SCRAM-SHA-256
which uses the SHA-256
hashing function.
SCRAM-SHA-256
Requires MongoDB 4.0 and featureCompatibilityVersion
to be set to 4.0.
To explicitly create a credential of type SCRAM-SHA-256
, use the
createScramSha256Credential
method:
String user; // the user name
String source; // the source where the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createScramSha256Credential(user, source, password);
and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string that explicitly specifies the authMechanism=SCRAM-SHA-256
. Using the new MongoClient API:
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-256");
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-256");
SCRAM-SHA-1
To explicitly create a credential of type SCRAM-SHA-1
, use the
createScramSha1Credential
method:
String user; // the user name
String source; // the source where the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createScramSha1Credential(user, source, password);
and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string that explicitly specifies the authMechanism=SCRAM-SHA-1
. Using the new MongoClient API:
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1");
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1");
MONGODB-CR
important
Starting in version 4.0, MongoDB removes support for the deprecated MongoDB Challenge-Response (MONGODB-CR
) authentication mechanism.
If your deployment has user credentials stored in MONGODB-CR
schema, you must upgrade to SCRAM
before you upgrade to version 4.0.
For information on upgrading to SCRAM
, see Upgrade to SCRAM.
To explicitly create a credential of type MONGODB-CR
use the createMongCRCredential
static factory method:
String user; // the user name
String database; // the name of the database in which the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createMongoCRCredential(user, database, password);
and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string that explicitly specifies the authMechanism=MONGODB-CR
. Using the new MongoClient API:
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR");
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR");
Note
After the authentication schema upgrade from MONGODB-CR to SCRAM, MONGODB-CR credentials will fail to authenticate.
X.509
With X.509 mechanism, MongoDB uses the X.509 certificate presented during SSL negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.
X.509 authentication requires the use of SSL connections with
certificate validation and is available in MongoDB 2.6 and later. To
create a credential of this type use the
createMongoX509Credential
static factory method:
String user; // The X.509 certificate derived user name, e.g. "CN=user,OU=OrgUnit,O=myOrg,..."
// ...
MongoCredential credential = MongoCredential.createMongoX509Credential(user);
and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string that explicitly specifies the authMechanism=MONGODB-X509
. Using the new MongoClient API:
MongoClient mongoClient = MongoClients.create("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&ssl=true");
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&ssl=true");
See the MongoDB server x.509 tutorial for more information about determining the subject name from the certificate.
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:
username
- value of yourAWS_ACCESS_KEY_ID
password
- value yourAWS_SECRET_ACCESS_KEY
hostname
- network address of your MongoDB server, accessible by your clientport
- port number of your MongoDB serverauthenticationDb
- MongoDB database that contains your user’s authentication data. If you omit this parameter, the driver uses the default valueadmin
.awsSessionToken
- value of yourAWS_SESSION_TOKEN
(optional)
Connection String
To specify the mechanism using a connection string, assign the
authMechanism
parameter the value MONGODB-AWS
in your connection string.
Your code to instantiate a MongoClient
should resemble the following:
MongoClient mongoClient = MongoClients.create("mongodb://<username>:<password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-AWS");
If you need to specify an AWS session token, include it in the
authMechanismProperties
parameter as follows using the format
AWS_SESSION_TOKEN:<awsSessionToken>
. Your code to instantiate a
MongoClient
with a session token should resemble the following:
MongoClient mongoClient = MongoClients.create("mongodb://<username>:<password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");
MongoCredential
To specify the mechanism using the MongoCredential class, use the
createAwsCredential()
method. Your code to instantiate a MongoClient
should resemble the following:
MongoCredential credential = MongoCredential.createAwsCredential("<username>", "<password>".toCharArray());
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", "<port>"))))
.credential(credential)
.build());
If you need to specify an AWS session token, you can add it using one of the following choices:
Specify your AWS Session Token in a Connection String
If you prefer to pass the AWS session token in the connection string, you
specify your authentication mechanism in the authMechanism
parameter
and your session token in the authMechanismProperties
parameter. Then,
add it to your MongoClientSettings
by calling the
applyConnectionString()
” >}})
method as follows:
MongoCredential credential = MongoCredential.createAwsCredential("<username>", "<password>".toCharArray());
String connectionString = "mongodb://<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyConnectionString(connectionString)
.credential(credential)
.build());
Specify your AWS Session Token in a MongoCredential
You can include your AWS session token in your MongoCredential
instance by
specifying it in a call to the
withMechanismProperty()
method as shown below:
MongoCredential.createAwsCredential("<username>", "<password>".toCharArray()) .withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>")
Specify your AWS Session Token in an Environment Variable
In your client execution environment, set an environment variable called
AWS_SESSION_TOKEN
and assign your token to it. The value is
automatically picked up by your MongoClient when you specify the
MONGODB-AWS
authentication mechanism.
Kerberos (GSSAPI)
MongoDB Enterprise supports proxy
authentication through Kerberos service. To create a credential of type
Kerberos (GSSAPI), use the
createGSSAPICredential
static factory method:
String user; // The Kerberos user name, including the realm, e.g. "user1@MYREALM.ME"
// ...
MongoCredential credential = MongoCredential.createGSSAPICredential(user);
and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string that explicitly specifies the authMechanism=GSSAPI
. Using the new MongoClient API:
MongoClient mongoClient = MongoClients.create("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI");
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI");
Note
The method refers to the GSSAPI
authentication mechanism instead
of Kerberos
because technically the driver authenticates via
the GSSAPI
SASL mechanism.
To successfully authenticate via Kerberos, the application typically must specify several system properties so that the underlying GSSAPI Java libraries can acquire a Kerberos ticket:
java.security.krb5.realm=MYREALM.ME
java.security.krb5.kdc=mykdc.myrealm.me
Depending on the Kerberos setup, additional property specifications may be required, either via the application code or, in some cases, the withMechanismProperty() method of the MongoCredential
instance:
For example, to specify the SERVICE_NAME
property via the MongoCredential
object:
credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "othername");
Or via the ConnectionString
:
mongodb://username%40MYREALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername
Note
On Windows, Oracle’s JRE uses LSA rather than SSPI in its implementation of GSSAPI, which limits interoperability with Windows Active Directory and in particular the ability to implement single sign-on.
LDAP (PLAIN)
MongoDB Enterprise supports proxy authentication through a Lightweight Directory
Access Protocol (LDAP) service. To create a credential of type LDAP use the
createPlainCredential
static factory method:
String user; // The LDAP user name
char[] password; // The LDAP password
// ...
MongoCredential credential = MongoCredential.createPlainCredential(user, "$external", password);
and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string that explicitly specifies the authMechanism=PLAIN
. Using the new MongoClient API:
MongoClient mongoClient = MongoClients.create("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");
or using the legacy MongoClient API:
MongoClient mongoClient = new MongoClient("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");
Note
The method refers to the plain
authentication mechanism instead
of LDAP
because technically the driver authenticates via the
PLAIN
SASL mechanism.