Authentication

MongoCredential

Include the following import statements:

import org.mongodb.scala._
import scala.collection.JavaConverters._

An authentication credential is represented as an instance of the MongoCredential class. The MongoCredential class includes helper methods for each of the supported authentication mechanisms.

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 authenticates by using the default authentication mechanism, regardless of server version, create a credential by using the createCredential() helper method:

val user: String = ...          // the user name
val source: String = ...        // the source where the user is defined
val password: Array[Char] = ... // the password as a character array
// ...
val credential = MongoCredential.createCredential(user, source, password)
val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
    .credential(credential)
    .build())

Or, you can use a connection string without explicitly specifying the authentication mechanism:

val mongoClient: MongoClient = MongoClient("mongodb://user1:pwd1@host1/?authSource=db1")

For challenge and response mechanisms, using the default authentication mechanism is the recommended approach, as it makes upgrading from MongoDB 2.6 to MongoDB 3.0 more simple, even after upgrading the authentication schema. For MongoDB 4.0 users, using the default authentication mechanism is also recommended as the mechanisms are checked and the correct hashing algorithm is used.

SCRAM-Based Mechanisms

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.

val user: String = ...          // the user name
val source: String = ...        // the source where the user is defined
val password: Array[Char] = ... // the password as a character array
// ...
val credential = MongoCredential.createScramSha256Credential(user, source, password)
val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
    .credential(credential)
    .build())

val mongoClient: MongoClient = MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-256")

val user: String = ...          // the user name
val source: String = ...        // the source where the user is defined
val password: Array[Char] = ... // the password as a character array
// ...
val credential = MongoCredential.createScramSha1Credential(user, source, password)
val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
    .credential(credential)
    .build())

val mongoClient: MongoClient = MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1")

MONGODB-CR

To explicitly create a credential of type MONGODB-CR use the createMongCRCredential() helper method:

val user: String = ...          // the user name
val source: String = ...        // the source where the user is defined
val password: Array[Char] = ... // the password as a character array
// ...
val credential = MongoCredential.createMongoCRCredential(user, database, password)
val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
    .credential(credential)
    .build())

Or, you can use a connection string that explicitly specifies authMechanism=MONGODB-CR:

val mongoClient: MongoClient = MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR")

X.509

With the 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. To create a credential of this type use the createMongoX509Credential() helper method:

val user: String = ...     // The X.509 certificate derived user name, e.g. "CN=user,OU=OrgUnit,O=myOrg,..."
// ...
val credential = MongoCredential.createMongoX509Credential(user)
val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
    .credential(credential)
    .build())

Or, you can use a connection string that explicitly specifies authMechanism=MONGODB-X509:

val mongoClient: MongoClient = MongoClient("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&ssl=true")

See the Use x.509 Certificates to Authenticate Clients tutorial in the Server manual to learn more about determining the subject name from the certificate.

Kerberos (GSSAPI)

MongoDB Enterprise supports proxy authentication through the Kerberos service. To create a credential of type Kerberos (GSSAPI), use the createGSSAPICredential() helper method:

val user: String = ...   // The Kerberos user name, including the realm, e.g. "user1@MYREALM.ME"
// ...
val credential = MongoCredential.createGSSAPICredential(user)
val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
    .credential(credential)
    .build())

Or, you can use a connection string that explicitly specifies authMechanism=GSSAPI:

val mongoClient: MongoClient = MongoClient("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI")

To successfully authenticate by using 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 might be required, either within the application code or, in some cases, by using the withMechanismProperty() method of the MongoCredential instance:

• SERVICE_NAME

• CANONICALIZE_HOST_NAME

• JAVA_SUBJECT

• JAVA_SASL_CLIENT_PROPERTIES

The following code shows how to specify the SERVICE_NAME property within the MongoCredential object:

val credentialWithProperty = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "othername")

Or, you can specify the SERVICE_NAME property within the ConnectionString:

val uri = "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() helper method:

val user: String = ...            // The LDAP user name
val password: Array[Char] = ...   // The LDAP password
// ...
val credential = MongoCredential.createPlainCredential(user, "$external", password)
val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("host1", 27017)).asJava))
    .credential(credential)
    .build())

Or, you can use a connection string that explicitly specifies authMechanism=PLAIN:

val mongoClient: MongoClient = MongoClient("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN")