Provided by: libmongoc-doc_1.15.0-1_all bug

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 (deprecated)

       · GSSAPI

       · PLAIN

       · X509

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

       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)

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

       2017-present, MongoDB, Inc