For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.
- MongoDB 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.MongoClientURI;
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 MongoClientURI
and pass it to a
MongoClient()
constructor that takes a MongoClientURI
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(new ServerAddress("host1", 27017), credential);
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:
MongoClientURI uri = new MongoClientURI("mongodb://user1:pwd1@host1/?authSource=db1");
MongoClient mongoClient = new MongoClient(uri);
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(new ServerAddress("host1", 27017), credential);
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:
MongoClientURI uri = new MongoClientURI("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-256");
MongoClient mongoClient = new MongoClient(uri);
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(new ServerAddress("host1", 27017), credential);
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:
MongoClientURI uri = new MongoClientURI("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1");
MongoClient mongoClient = new MongoClient(uri);
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(new ServerAddress("host1", 27017), credential);
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:
MongoClientURI uri = new MongoClientURI("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR");
MongoClient mongoClient = new MongoClient(uri);
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);
MongoClientOptions options = MongoClientOptions.builder().sslEnabled(true).build();
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(new ServerAddress("host1", 27017), credential, options);
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:
MongoClientURI uri = new MongoClientURI("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&ssl=true");
MongoClient mongoClient = new MongoClient(uri);
See the MongoDB server x.509 tutorial for more information about determining the subject name from the certificate.
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(new ServerAddress("host1", 27017), credential);
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:
MongoClientURI uri = new MongoClientURI("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(new ServerAddress("host1", 27017), credential);
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:
MongoClientURI uri = new MongoClientURI("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.