bionic (3) mongoc_authentication.3.gz

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