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;
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.
To specify a list of these instances, use one of
several MongoClient()
constructors that take a parameter of type
List <MongoCredential>
.
To specify a single MongoCredential
, you can also use a MongoClientURI
and pass it to a MongoClient()
constructor that takes a MongoClientURI
parameter.
Note
Given the flexibility of role-based access control in MongoDB, it is usually sufficient to authenticate with a single user, but, for completeness, the driver accepts a list of credentials.
Default Authentication Mechanism
Starting in MongoDB 3.0, MongoDB changed the default authentication
mechanism from MONGODB-CR
to
SCRAM-SHA-1
.
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 database; // the name of the database in which the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createCredential(user, database, password);
MongoClient mongoClient = new MongoClient(new ServerAddress("host1", 27017),
Arrays.asList(credential));
Or use a connection string without explicitly specifying the authentication mechanism:
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 the approach will make upgrading from MongoDB 2.6 to MongoDB 3.0 seamless, even after upgrading the authentication schema.
SCRAM-SHA-1
To explicitly create a credential of type SCRAM-SHA-1
, use the createScramSha1Credential
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.createScramSha1Credential(user,
database,
password);
MongoClient mongoClient = new MongoClient(new ServerAddress("host1", 27017),
Arrays.asList(credential));
Or use a connection string that explicitly specifies the
authMechanism=SCRAM-SHA-1
:
MongoClientURI uri = new MongoClientURI("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1");
MongoClient mongoClient = new MongoClient(uri);
MONGODB-CR
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);
MongoClient mongoClient = new MongoClient(new ServerAddress("host1", 27017),
Arrays.asList(credential));
Or use a connection string that explicitly specifies the
authMechanism=MONGODB-CR
:
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-SHA-1, 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();
MongoClient mongoClient = new MongoClient(new ServerAddress("host1", 27017),
Arrays.asList(credential), options);
Or use a connection string that explicitly specifies the
authMechanism=MONGODB-X509
:
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);
Or use a connection string that explicitly specifies the
authMechanism=GSSAPI
:
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
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);
Or use a connection string that explicitly specifies the
authMechanism=PLAIN
:
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.