Authentication

Basic Authentication (SCRAM-SHA-256)

MongoDB 4.0 introduces support for authenticating using the SCRAM protocol with the more secure SHA-256 hash described in RFC 7677. Using this authentication mechanism means that the password is never actually sent over the wire when authenticating, but rather a computed proof that the client password is the same as the password the server knows. In MongoDB 4.0, the C driver can determine the correct default authentication mechanism for users with stored SCRAM-SHA-1 and SCRAM-SHA-256 credentials:

mongoc_client_t *client =  mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
/* the correct authMechanism is negotiated between the driver and server. */

Alternatively, SCRAM-SHA-256 can be explicitly specified as an authMechanism.

mongoc_client_t *client =  mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-256&authSource=mydb");

Basic Authentication (SCRAM-SHA-1)

The default authentication mechanism before MongoDB 4.0 is SCRAM-SHA-1 (RFC 5802). Using this authentication mechanism means that the password is never actually sent over the wire when authenticating, but rather a computed proof that the client password is the same as the password the server knows.

mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-1&authSource=mydb");

Legacy Authentication (MONGODB-CR)

The MONGODB-CR authMechanism is deprecated and will no longer function in MongoDB 4.0. Instead, specify no authMechanism and the driver will use an authentication mechanism compatible with your server.

GSSAPI (Kerberos) Authentication

GSSAPI (Kerberos) authentication is available in the Enterprise Edition of MongoDB. To authenticate using GSSAPI, the MongoDB C driver must be installed with SASL support.

On UNIX-like environments, run the kinit command before using the following authentication methods:

$ kinit mongodbuser@EXAMPLE.COM
mongodbuser@EXAMPLE.COM's Password:
$ klistCredentials cache: FILE:/tmp/krb5cc_1000
       Principal: mongodbuser@EXAMPLE.COM
 Issued                Expires               Principal
Feb  9 13:48:51 2013  Feb  9 23:48:51 2013  krbtgt/EXAMPLE.COM@EXAMPLE.COM

Now authenticate using the MongoDB URI. GSSAPI authenticates against the $external virtual database, so a database does not need to be specified in the URI. Note that the Kerberos principal must be URL-encoded:

mongoc_client_t *client;
client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI");

The driver supports these GSSAPI properties:

• CANONICALIZE_HOST_NAME: This might be required with Cyrus-SASL when the hosts report different hostnames than what is used in the Kerberos database. The default is "false".

• SERVICE_NAME: Use a different service name than the default, "mongodb".

Set properties in the URL:

mongoc_client_t *client;
client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI&"
                            "authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");

If you encounter errors such as Invalid net address, check if the application is behind a NAT (Network Address Translation) firewall. If so, create a ticket that uses forwardable and addressless Kerberos tickets. This can be done by passing -f -A to kinit.

$ kinit -f -A mongodbuser@EXAMPLE.COM

SASL Plain Authentication

MongoDB Enterprise Edition supports the SASL PLAIN authentication mechanism, initially intended for delegating authentication to an LDAP server. Using the SASL PLAIN mechanism is very similar to the challenge response mechanism with usernames and passwords. This authentication mechanism uses the $external virtual database for LDAP support:

mongoc_client_t *client;
client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN");

PLAIN authenticates against the $external database, so specifying the authSource database is not required.

X.509 Certificate Authentication

$ mongod --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem

The MONGODB-X509 mechanism authenticates a username derived from the distinguished subject name of the X.509 certificate presented by the driver during TLS negotiation. This authentication method requires the use of TLS connections with certificate validation.

mongoc_client_t *client;
mongoc_ssl_opt_t ssl_opts = { 0 };
ssl_opts.pem_file = "mycert.pem";
ssl_opts.pem_pwd = "mycertpassword";
ssl_opts.ca_file = "myca.pem";
ssl_opts.ca_dir = "trust_dir";
ssl_opts.weak_cert_validation = false;
client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
mongoc_client_set_ssl_opts (client, &ssl_opts);

MONGODB-X509 authenticates against the $external database, so specifying the authSource database is not required. For more information on the x509_derived_username, see the MongoDB server x.509 tutorial.

Authentication via AWS IAM

The MONGODB-AWS mechanism authenticates to MongoDB servers with credentials provided by AWS Identity and Access Management (IAM).

To authenticate, create a user with an associated Amazon Resource Name (ARN) on the $external database, and specify the MONGODB-AWS authMechanism in the URI.

mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost/?authMechanism=MONGODB-AWS");

Since MONGODB-AWS always authenticates against the $external database, so specifying the authSource database is not required.

Credentials include the access key id, secret access key, and optional session token. They may be obtained from the following ways.

mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS");

mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");