Provided by: libmongoc-doc_1.26.0-1.1ubuntu2_all 
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");
NOTE:
SCRAM-SHA-1 authenticates against the admin database by default. If the user is created in another
database, then specifying the authSource is required.
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
NOTE:
On UNIX-like environments, Kerberos support requires compiling the driver against cyrus-sasl.
On Windows, Kerberos support requires compiling the driver against Windows Native SSPI or cyrus-sasl.
The default configuration of the driver will use Windows Native SSPI.
To modify the default configuration, use the cmake option ENABLE_SASL.
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:
GSSAPI authenticates against the $external database, so specifying the authSource database is not
required.
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
NOTE:
The MongoDB C Driver must be compiled with SASL support in order to use 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:
SASL PLAIN is a clear-text authentication mechanism. It is strongly recommended to connect to MongoDB
using TLS with certificate validation when using the PLAIN mechanism.
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
NOTE:
The MongoDB C Driver must be compiled with TLS support for X.509 authentication support. Once this is
done, start a server with the following options:
$ 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.
NOTE:
The MongoDB C Driver will attempt to determine the x509 derived username when none is provided, and as
of MongoDB 3.4 providing the username is not required at all.
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.
AWS credentials via URI
Credentials may be passed directly in the URI as username/password.
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS");
This may include a session token passed with authMechanismProperties.
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");
AWS credentials via environment
If credentials are not passed through the URI, libmongoc will check for the following environment
variables.
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN (optional)
AWS Credentials via ECS
If credentials are not passed in the URI or with environment variables, libmongoc will check if the
environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is set, and if so, attempt to retrieve
temporary credentials from the ECS task metadata by querying a link local address.
AWS Credentials via EC2
If credentials are not passed in the URI or with environment variables, and the environment variable
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is not set, libmongoc will attempt to retrieve temporary
credentials from the EC2 machine metadata by querying link local addresses.
AUTHOR
MongoDB, Inc
COPYRIGHT
2017-present, MongoDB, Inc