- MongoDB Async 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;
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 connection string and pass it to a
MongoClients.create()
method.
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);
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
Or use a connection string that does not specify the authentication mechanism:
MongoClient mongoClient = MongoClients.create("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);
MongoClient mongoClient = MongoClients.create(
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
:
MongoClient mongoClient = MongoClients.create("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);
MongoClient mongoClient = MongoClients.create(
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`:
```java
MongoClient mongoClient = MongoClients.create("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:
MongoCredential credential = MongoCredential.createMongoCRCredential(user, source, password);
MongoClient mongoClient = MongoClients.create(
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
:
MongoClient mongoClient = MongoClients.create("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);
EventLoopGroup eventLoopGroup = new NioEventLoopGroup(); // make sure application shuts this down
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.streamFactoryFactory(NettyStreamFactoryFactory.builder().eventLoopGroup(eventLoopGroup).build())
.applyToSslSettings(builder -> builder.enabled(true))
.build());
Or use a connection string that explicitly specifies the authMechanism=MONGODB-X509
:
MongoClient mongoClient = MongoClients.create("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&streamType=netty&ssl=true");
Note
The streamType connection string query parameter is deprecated as of the 3.10 release and will be removed in the next major release.
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);
MongoClient mongoClient = MongoClients.create(
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
:
MongoClient mongoClient = MongoClients.create("mongodb://username%40MYREALM.ME@host1/?authMechanism=GSSAPI");
Note
The method refers to the GSSAPI
authentication mechanism instead of Kerberos
because technically the driver is authenticating 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 a connection string:
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);
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
.credential(credential)
.build());
or with a connection string:
MongoClient mongoClient = MongoClients.create("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");
Note
The method refers to the plain
authentication mechanism instead of LDAP
because technically the driver is authenticating via the PLAIN SASL mechanism.