- Reference
- Driver
- Connecting
- Authentication
Authentication
The .NET driver supports all MongoDB authentication mechanisms including those in the Enterprise Edition.
Authentication credentials are created by the application as instances of MongoCredential
which includes static factory methods for each of the supported authentication mechanisms. A list of these instances must be passed to the driver using the MongoClient constructor
that takes a MongoClientSettings
. When only one credential is necessary, it is possible to specify via the connection string.
Default
MongoDB 4.0 now uses SCRAM (Salted Challenge Response Authentication Mechanism) as the default mechanism and no longer supports MONGODB-CR. To create a credential that will authenticate properly regardless of server version, create a credential using the following static factory method.
var credential = MongoCredential.CreateCredential(databaseName, username, password);
Or via the connection string:
mongodb://username:password@myserver/databaseName
These are the recommended approaches as it will make upgrading from MongoDB 2.6 to MongoDB 3.0 seamless, before and after upgrading the authentication schema. For MongoDB 4.0, the above approaches will automatically determine which version of SCRAM should be used (SCRAM-SHA-1 or SCRAM-SHA-256).
Note
The databaseName part of the connection string indicates which database the credentials are located in. See the connection string section for more information on connection strings.SCRAM
When connecting to a MongoDB 4.0 server without specifying an authentication mechanism, the driver will negotiate with the server to determine whether SCRAM-SHA-1 or SCRAM-SHA-256 is the appropriate mechanism.
SCRAM-SHA-256
SCRAM-SHA-256 is the default authentication mechanism chosen as long as the user’s authentication mechanism supports it. (See the mechanism parameter of createUser() and the “Supported Authentication Methods: Defaults” section of the Driver Authentication Specification for additional information.
SecureStrings
SecureStrings are slightly less secure when used in conjunction with SCRAM-SHA-256, due to the need to temporarily store the cleartext password in a managed memory string in order to SASLPrep it. This behavior is no different from other drivers in languages with managed memory. (SCRAM-SHA-1 is not affected.)
.NET Standard support
In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII passwords because SASLPrep is not fully implemented due to the lack of a string normalization function in .NET Standard 1.5. Normalizing the password into Unicode Normalization Form KC beforehand MAY help. SCRAM-SHA-1 is the recommended alternative for now. See RFC5802 and the SCRAM-SHA-256 section of the Driver Authentication specification for additional information.
x.509 Authentication
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.
There are two ways to create a credential of this type:
Programmatically, using the following static factory method:
var credential = MongoCredential.CreateX509Credential(username);
When configuring x.509 authentication programmatically, the
username
parameter provided toCreateX509Credential
must match the distinguished subject name of your x.509 certificate exactly. To determine the exactusername
required for your x.509 connection, consult the MongoDB server x.509 tutorial. Alternatively, anynull
username
parameter provided toCreateX509Credential
will cause the MongoDB server to infer a username based on the distinguished subject name of the x.509 certificate. Using anull
username value can help prevent issues when certificates are updated, since you can avoid managing ausername
value and a certificate as separate entities in your environment.Manually, using connection string options:
mongodb://myserver/?authMechanism=MONGODB-X509
When configuring x.509 authentication from a connection string, you must still provide the certificate programmatically via
MongoClientSettings
. Any connection string specifying x.509 authentication must be imported into aMongoClientSettings
object usingMongoClientSettings.FromConnectionString
to add the certificate to the configuration.
You can use certificates via the trust stores on your computer, or a PKCS #12 (.pfx
) file. To be used with client authentication, the X509Certificate
provided to the driver must contain the PrivateKey
.
For testing purposes, the AllowInsecureTls
field of your MongoClientSettings
can be set to true
to allow the use of self-signed certificates. Since this setting bypasses the validation of certificates entirely, it should never be used for production uses.
Connecting using a MongoClientSettings
object built from a connection string:
var connectionString = "mongodb://myserver/?authMechanism=MONGODB-X509";
var settings = MongoClientSettings.FromConnectionString(connectionString);
settings.useTls = true;
settings.SslSettings = new SslSettings
{
ClientCertificates = new List<X509Certificate>()
{
new X509Certificate2("client-certificate.pfx", "password")
}
};
// For testing using self-signed certs, use this option to skip validation.
// DO NOT USE THIS OPTION FOR PRODUCTION USES
settings.AllowInsecureTls = true;
Connecting using a MongoClientSettings
object built from scratch:
var settings = new MongoClientSettings
{
// if a username is null, the distinguished name from the certificate will be used
Credential = MongoCredential.CreateMongoX509Credential(null),
SslSettings = new SslSettings
{
ClientCertificates = new List<X509Certificate>()
{
new X509Certificate2("client-certificate.pfx", "password")
},
},
UseTls = true,
Server = new MongoServerAddress("myserver", 27017),
// For testing using self-signed certs, use this option to skip validation.
// DO NOT USE THIS OPTION FOR PRODUCTION USES
AllowInsecureTls = true
};
GSSAPI/Kerberos
MongoDB Enterprise supports authentication using Kerberos/GSSAPI. To create a Kerberos/GSSAPI credential, use the following method:
var credential = MongoCredential.CreateGssapiCredential(username, password);
Or via the connection string:
mongodb://username%40REALM.com:password@myserver/?authMechanism=GSSAPI
Note
Note that the username will need to have a REALM associated with it. When used in a connection string,%40
is the escape character for the @
symbol.
If the process owner running your application is the same as the user needing authentication, you can omit the password:
var credential = MongoCredential.CreateGssapiCredential(username);
Or via the connection string:
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI
Depending on the kerberos setup, it may be required to specify some additional properties. These may be specified in the connection string or via code.
CANONICALIZE_HOST_NAME
Uses the DNS server to retrieve the fully qualified domain name (FQDN) of the host.
credential = credential.WithMechanismProperty("CANONICALIZE_HOST_NAME", "true");
Or via the connection string:
mongodb://username@myserver/?authMechanism=GSSAPI&authMechanismProperties=CANONICALIZE_HOSTNAME:true
REALM
This is used when the user’s realm is different from the service’s realm.
credential = credential.WithMechanismProperty("REALM", "otherrealm");
Or via the connection string:
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=REALM:otherrealm
SERVICE_NAME
This is used when the service’s name is different that the default
mongodb
.credential = credential.WithMechanismProperty("SERVICE_NAME", "othername");
Or via the connection string:
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername
In addition, it is possible to use multiple authentication mechanism properties either via code or in the connection string. In code, call WithMechanismProperty
multiple times. In the connection string, separate the entries with a ,
(comma).
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername,REALM:otherrealm
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:
var credential = MongoCredential.CreatePlainCredential("$external", username, password);
Or via the connection string:
mongodb://username:password@myserver/?authSource=$external&authMechanism=PLAIN