.\" Man page generated from reStructuredText. . .TH "MONGOC_AUTHENTICATION" "3" "Jun 04, 2021" "1.17.6" "libmongoc" .SH NAME mongoc_authentication \- Authentication . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .sp 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 \fI\%MongoDB security documentation\fP\&. .sp The MongoDB C driver supports several authentication mechanisms through the use of MongoDB connection URIs. .sp 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. .sp To select a specific authentication mechanism other than the default, see the list of supported mechanism below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb"); .ft P .fi .UNINDENT .UNINDENT .sp Currently supported values for the authMechanism connection string option are: .INDENT 0.0 .IP \(bu 2 \fI\%SCRAM\-SHA\-1\fP .IP \(bu 2 \fI\%MONGODB\-CR (deprecated)\fP .IP \(bu 2 \fI\%GSSAPI\fP .IP \(bu 2 \fI\%PLAIN\fP .IP \(bu 2 \fI\%X509\fP .IP \(bu 2 \fI\%MONGODB\-AWS\fP .UNINDENT .SH BASIC AUTHENTICATION (SCRAM-SHA-256) .sp MongoDB 4.0 introduces support for authenticating using the SCRAM protocol with the more secure SHA\-256 hash described in \fI\%RFC 7677\fP\&. 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb"); /* the correct authMechanism is negotiated between the driver and server. */ .ft P .fi .UNINDENT .UNINDENT .sp Alternatively, SCRAM\-SHA\-256 can be explicitly specified as an authMechanism. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM\-SHA\-256&authSource=mydb"); .ft P .fi .UNINDENT .UNINDENT .sp Passwords for SCRAM\-SHA\-256 undergo the preprocessing step known as SASLPrep specified in \fI\%RFC 4013\fP\&. 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. .sp Usernames \fInever\fP undergo SASLPrep. .sp By default, when building the C driver libicu is linked if available. This can be changed with the \fBENABLE_ICU\fP cmake option. To specify an installation path of libicu, specify \fBICU_ROOT\fP as a cmake option. See the \fI\%FindICU\fP documentation for more information. .SH BASIC AUTHENTICATION (SCRAM-SHA-1) .sp The default authentication mechanism before MongoDB 4.0 is \fBSCRAM\-SHA\-1\fP (\fI\%RFC 5802\fP). 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM\-SHA\-1&authSource=mydb"); .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBSCRAM\-SHA\-1\fP authenticates against the \fBadmin\fP database by default. If the user is created in another database, then specifying the authSource is required. .UNINDENT .UNINDENT .SH LEGACY AUTHENTICATION (MONGODB-CR) .sp 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. .SH GSSAPI (KERBEROS) AUTHENTICATION .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Kerberos support requires compiling the driver against \fBcyrus\-sasl\fP on UNIX\-like environments. On Windows, configure the driver to build against the Windows Native SSPI. .UNINDENT .UNINDENT .sp \fBGSSAPI\fP (Kerberos) authentication is available in the Enterprise Edition of MongoDB. To authenticate using \fBGSSAPI\fP, the MongoDB C driver must be installed with SASL support. .sp On UNIX\-like environments, run the \fBkinit\fP command before using the following authentication methods: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ kinit mongodbuser@EXAMPLE.COM mongodbuser@EXAMPLE.COM\(aqs 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 .ft P .fi .UNINDENT .UNINDENT .sp Now authenticate using the MongoDB URI. \fBGSSAPI\fP authenticates against the \fB$external\fP virtual database, so a database does not need to be specified in the URI. Note that the Kerberos principal \fImust\fP be URL\-encoded: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_client_t *client; client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo\-server.example.com/?authMechanism=GSSAPI"); .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBGSSAPI\fP authenticates against the \fB$external\fP database, so specifying the authSource database is not required. .UNINDENT .UNINDENT .sp The driver supports these GSSAPI properties: .INDENT 0.0 .IP \(bu 2 \fBCANONICALIZE_HOST_NAME\fP: 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". .IP \(bu 2 \fBSERVICE_NAME\fP: Use a different service name than the default, "mongodb". .UNINDENT .sp Set properties in the URL: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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"); .ft P .fi .UNINDENT .UNINDENT .sp If you encounter errors such as \fBInvalid net address\fP, check if the application is behind a NAT (Network Address Translation) firewall. If so, create a ticket that uses \fBforwardable\fP and \fBaddressless\fP Kerberos tickets. This can be done by passing \fB\-f \-A\fP to \fBkinit\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ kinit \-f \-A mongodbuser@EXAMPLE.COM .ft P .fi .UNINDENT .UNINDENT .SH SASL PLAIN AUTHENTICATION .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The MongoDB C Driver must be compiled with SASL support in order to use \fBSASL PLAIN\fP authentication. .UNINDENT .UNINDENT .sp MongoDB Enterprise Edition supports the \fBSASL PLAIN\fP authentication mechanism, initially intended for delegating authentication to an LDAP server. Using the \fBSASL PLAIN\fP mechanism is very similar to the challenge response mechanism with usernames and passwords. This authentication mechanism uses the \fB$external\fP virtual database for \fBLDAP\fP support: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBSASL PLAIN\fP is a clear\-text authentication mechanism. It is strongly recommended to connect to MongoDB using TLS with certificate validation when using the \fBPLAIN\fP mechanism. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_client_t *client; client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN"); .ft P .fi .UNINDENT .UNINDENT .sp \fBPLAIN\fP authenticates against the \fB$external\fP database, so specifying the authSource database is not required. .SH X.509 CERTIFICATE AUTHENTICATION .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ mongod \-\-tlsMode requireTLS \-\-tlsCertificateKeyFile server.pem \-\-tlsCAFile ca.pem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp The \fBMONGODB\-X509\fP 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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); .ft P .fi .UNINDENT .UNINDENT .sp \fBMONGODB\-X509\fP authenticates against the \fB$external\fP database, so specifying the authSource database is not required. For more information on the x509_derived_username, see the MongoDB server \fI\%x.509 tutorial\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .SH AUTHENTICATION VIA AWS IAM .sp The \fBMONGODB\-AWS\fP mechanism authenticates to MongoDB servers with credentials provided by AWS Identity and Access Management (IAM). .sp To authenticate, create a user with an associated Amazon Resource Name (ARN) on the \fB$external\fP database, and specify the \fBMONGODB\-AWS\fP \fBauthMechanism\fP in the URI. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost/?authMechanism=MONGODB\-AWS"); .ft P .fi .UNINDENT .UNINDENT .sp Since \fBMONGODB\-AWS\fP always authenticates against the \fB$external\fP database, so specifying the authSource database is not required. .sp Credentials include the \fBaccess key id\fP, \fBsecret access key\fP, and optional \fBsession token\fP\&. They may be obtained from the following ways. .SS AWS credentials via URI .sp Credentials may be passed directly in the URI as username/password. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_uri_t *uri = mongoc_uri_new ("mongodb://:localhost/?authMechanism=MONGODB\-AWS"); .ft P .fi .UNINDENT .UNINDENT .sp This may include a \fBsession token\fP passed with \fBauthMechanismProperties\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoc_uri_t *uri = mongoc_uri_new ("mongodb://:localhost/?authMechanism=MONGODB\-AWS&authMechanismProperties=AWS_SESSION_TOKEN:"); .ft P .fi .UNINDENT .UNINDENT .SS AWS credentials via environment .sp If credentials are not passed through the URI, libmongoc will check for the following environment variables. .INDENT 0.0 .IP \(bu 2 AWS_ACCESS_KEY_ID .IP \(bu 2 AWS_SECRET_ACCESS_KEY .IP \(bu 2 AWS_SESSION_TOKEN (optional) .UNINDENT .SS AWS Credentials via ECS .sp If credentials are not passed in the URI or with environment variables, libmongoc will check if the environment variable \fBAWS_CONTAINER_CREDENTIALS_RELATIVE_URI\fP is set, and if so, attempt to retrieve temporary credentials from the ECS task metadata by querying a link local address. .SS AWS Credentials via EC2 .sp If credentials are not passed in the URI or with environment variables, and the environment variable \fBAWS_CONTAINER_CREDENTIALS_RELATIVE_URI\fP is not set, libmongoc will attempt to retrieve temporary credentials from the EC2 machine metadata by querying link local addresses. .SH AUTHOR MongoDB, Inc .SH COPYRIGHT 2017-present, MongoDB, Inc .\" Generated by docutils manpage writer. .