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 the MongoClientSettings and pass as a parameter to the MongoClients.create() method.

To specify a single MongoCredential instance, you can also use the ConnectionString and pass to a MongoClients.create() method.

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);

ClusterSettings clusterSettings = ClusterSettings.builder()
                                  .hosts(asList(new ServerAddress("localhost"))).build();
MongoClientSettings settings = MongoClientSettings.builder()
                                  .clusterSettings(clusterSettings)
                                  .credentialList(Arrays.asList(credential))
                                  .build();
MongoClient mongoClient = MongoClients.create(settings);

Or use a ConnectionString instance that does not specify the authentication mechanism:

MongoClient mongoClient = MongoClients.create(
            new ConnectionString("mongodb://user1:pwd1@host1/?authSource=db1"));

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:

MongoCredential credential = MongoCredential.createScramSha1Credential(user,
                                                                       database,
                                                                       password);

ClusterSettings clusterSettings = ClusterSettings.builder()
                                  .hosts(asList(new ServerAddress("localhost"))).build();
MongoClientSettings settings = MongoClientSettings.builder()
                                  .clusterSettings(clusterSettings)
                                  .credentialList(Arrays.asList(credential))
                                  .build();
MongoClient mongoClient = MongoClients.create(settings);

Or use a ConnectionString instance that explicitly specifies the authMechanism=SCRAM-SHA-1:

MongoClient mongoClient = MongoClients.create(new ConnectionString(
            "mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1"));

MONGODB-CR

To explicitly create a credential of type MONGODB-CR use the createMongCRCredential static factory method:

MongoCredential credential = MongoCredential.createMongoCRCredential(user,
                                                                     database,
                                                                     password);
ClusterSettings clusterSettings = ClusterSettings.builder()
                                  .hosts(asList(new ServerAddress("localhost"))).build();
MongoClientSettings settings = MongoClientSettings.builder()
                                  .clusterSettings(clusterSettings)
                                  .credentialList(Arrays.asList(credential))
                                  .build();
MongoClient mongoClient = MongoClients.create(settings);

Or use a ConnectionString instance that explicitly specifies the authMechanism=MONGODB-CR:

MongoClient mongoClient = MongoClients.create(new ConnectionString(
            "mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR"));

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);
ClusterSettings clusterSettings = ClusterSettings.builder()
                                  .hosts(asList(new ServerAddress("localhost"))).build();

EventLoopGroup eventLoopGroup = new NioEventLoopGroup();  // make sure application shuts this down

MongoClientSettings settings = MongoClientSettings.builder()
                .clusterSettings(clusterSettings)
                .credentialList(Arrays.asList(credential))
                .streamFactoryFactory(NettyStreamFactoryFactory.builder().eventLoopGroup(eventLoopGroup).build())
                .sslSettings(SslSettings.builder().enabled(true).build())
                .build();
MongoClient mongoClient = MongoClients.create(settings);

Or use a ConnectionString instance that explicitly specifies the authMechanism=MONGODB-X509:

MongoClient mongoClient = MongoClients.create(new ConnectionString(
            "mongodb://subjectName@host1/?authMechanism=MONGODB-X509&streamType=netty&ssl=true"));

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);
ClusterSettings clusterSettings = ClusterSettings.builder()
                                  .hosts(asList(new ServerAddress("localhost"))).build();
MongoClientSettings settings = MongoClientSettings.builder()
                                  .clusterSettings(clusterSettings)
                                  .credentialList(Arrays.asList(credential))
                                  .build();
MongoClient mongoClient = MongoClients.create(settings);

Or use a ConnectionString that explicitly specifies the authMechanism=GSSAPI:

MongoClient mongoClient = MongoClients.create(new ConnectionString(
            "mongodb://username%40MYREALM.ME@host1/?authMechanism=GSSAPI"));

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:

• SERVICE_NAME

• CANONICALIZE_HOST_NAME

• JAVA_SUBJECT

• JAVA_SASL_CLIENT_PROPERTIES

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

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);
ClusterSettings clusterSettings = ClusterSettings.builder()
                                  .hosts(asList(new ServerAddress("localhost"))).build();
MongoClientSettings settings = MongoClientSettings.builder()
                                  .clusterSettings(clusterSettings)
                                  .credentialList(Arrays.asList(credential))
                                  .build();
MongoClient mongoClient = MongoClients.create(settings);

or with a connection string:

MongoClient mongoClient = MongoClients.create(new ConnectionString(
          "mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN"));