NAME¶

This guide covers the use of authentication options with the MongoDB C Driver. Ensure that the MongoDB server is also properly configured for authentication before making a connection. For more information, see the MongoDB security documentation.

The MongoDB C driver supports several authentication mechanisms through the use of MongoDB connection URIs.

By default, if a username and password are provided as part of the connection string (and an optional authentication database), they are used to connect via the default authentication mechanism of the server.

To select a specific authentication mechanism other than the default, see the list of supported mechanism below.

mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");

Currently supported values for the authMechanism connection string option are:

BASIC AUTHENTICATION (SCRAM-SHA-256)¶

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

Passwords for SCRAM-SHA-256 undergo the preprocessing step known as SASLPrep specified in RFC 4013. SASLPrep will only be performed for passwords containing non-ASCII characters. SASLPrep requires libicu. If libicu is not available, attempting to authenticate over SCRAM-SHA-256 with non-ASCII passwords will result in error.

Usernames never undergo SASLPrep.

By default, when building the C driver libicu is linked if available. This can be changed with the ENABLE_ICU cmake option. To specify an installation path of libicu, specify ICU_ROOT as a cmake option. See the FindICU documentation for more information.

BASIC AUTHENTICATION (SCRAM-SHA-1)¶

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

NOTE:

LEGACY AUTHENTICATION (MONGODB-CR)¶

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

NOTE:

The driver supports these GSSAPI properties:

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:

NOTE:

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 --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile 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 SSL negotiation. This authentication method requires the use of SSL 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.

NOTE:

AUTHOR¶

COPYRIGHT¶