NAME

       mongoc_authentication - Authentication

       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:

       • SCRAM-SHA-1

       • MONGODB-CR

       • GSSAPI

       • PLAIN

       • X509

BASIC AUTHENTICATION (SCRAM-SHA-1)

       The  default authentication mechanism when talking to MongoDB 3.0 and later 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 a challenge response authentication mechanism. It was the
       default mechanism until MongoDB 3.0 and is being phased out. It is strongly suggested that
       users upgrade to SCRAM-SHA-1.

       NOTE:
          MONGODB-CR  authenticates against the admin database by default. If the user is created
          in another database, then specifying the authSource is required.

GSSAPI (KERBEROS) AUTHENTICATION

       NOTE:
          Kerberos  support  requires  compiling  the  driver  against  cyrus-sasl  on  UNIX-like
          environments.  On  Windows,  configure  the  driver to build against the Windows Native
          SSPI.

       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  SSL  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  SSL support for X.509 authentication
          support. Once this is done, start a server with the following options:

              $ 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:
          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.

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2018, MongoDB, Inc