Authentication

The Scala driver supports all MongoDB authentication mechanisms, including those only available in the MongoDB Enterprise Edition.

An authentication credential is represented as an instance of the MongoCredential class, which includes static factory methods for each of the supported authentication mechanisms. A list of these instances must be passed to the driver via a MongoClient static factory method that takes a MongoClientSettings parameter. Alternatively, a single MongoCredential can be created implicity via a ConnectionString and passed to a MongoClient static factory method that takes a ConnectionString parameter.

Default authentication mechanism

MongoDB 3.0 changed the default authentication mechanism from MONGODB-CR to SCRAM-SHA-1. To create a credential that will authenticate properly regardless of server version, create a credential using the following static factory method:

import com.mongodb.MongoCredential._

// ...

val user: String = "userName"                       // the user name
val database: String = "databaseName"               // the name of the database in which the user is defined
val password: Array[Char] = "password".toCharArray  // the password as a character array
// ...
val credential: MongoCredential = createCredential(user, database, password)

or with a connection string:

val uri: String = "mongodb://user1:pwd1@host1/?authSource=db1"

This is the recommended approach as it 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 following static factory method:

val credential: MongoCredential = createScramSha1Credential(user, database, password)

or with a connection string:

val uri: String = "mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1"

MONGODB-CR

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

val credential: MongoCredential = createMongoCRCredential(user, database, password)

or with a connection string:

val uri: String = "mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR"

Note that this is not recommended as a credential created in this way will fail to authenticate after an authentication schema upgrade from MONGODB-CR to SCRAM-SHA-1.

x.509

The x.509 mechanism authenticates a user whose name is derived from the distinguished subject name of the X.509 certificate presented by the driver during SSL negotiation. This authentication method requires the use of SSL connections with certificate validation and is available in MongoDB 2.6 and newer. To create a credential of this type use the following static factory method:

val user: String = "..."     // The x.509 certificate derived user name, e.g. "CN=user,OU=OrgUnit,O=myOrg,..."
val credential: MongoCredential = createMongoX509Credential(user)

or with a connection string:

val uri: String = "mongodb://subjectName@host1/?authMechanism=MONGODB-X509"

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 a Kerberos service. To create a credential of type Kerberos (GSSAPI) use the following static factory method:

val user: String = "..."   // The Kerberos user name, including the realm, e.g. "user1@MYREALM.ME"
// ...
val credential: MongoCredential = createGSSAPICredential(user)

or with a connection string:

val uri: String = "mongodb://username%40REALM.com@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

LDAP (PLAIN)

MongoDB Enterprise supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. To create a credential of type LDAP use the following static factory method:

val user: String = "..."                        // The LDAP user name
val password: Array[Char] = "...".toCharArray   // The LDAP password

// ...
val credential: MongoCredential = createPlainCredential(user, "$external", password)

or with a connection string:

val uri: String = "mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN"