1MONGOC_AUTHENTICATION(3) libmongoc MONGOC_AUTHENTICATION(3)
2
6 mongoc_authentication - Authentication
7 This guide covers the use of authentication options with the MongoDB C
9 Driver. Ensure that the MongoDB server is also properly configured for
10 authentication before making a connection. For more information, see
11 the MongoDB security documentation.
12 The MongoDB C driver supports several authentication mechanisms through
14 the use of MongoDB connection URIs.
15 By default, if a username and password are provided as part of the con‐
17 nection string (and an optional authentication database), they are used
18 to connect via the default authentication mechanism of the server.
19 To select a specific authentication mechanism other than the default,
21 see the list of supported mechanism below.
22 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
24 Currently supported values for the authMechanism connection string op‐
26 tion are:
27 • SCRAM-SHA-1
29 • MONGODB-CR (deprecated)
31 • GSSAPI
33 • PLAIN
35 • X509
37 • MONGODB-AWS
39
41 MongoDB 4.0 introduces support for authenticating using the SCRAM pro‐
42 tocol with the more secure SHA-256 hash described in RFC 7677. Using
43 this authentication mechanism means that the password is never actually
44 sent over the wire when authenticating, but rather a computed proof
45 that the client password is the same as the password the server knows.
46 In MongoDB 4.0, the C driver can determine the correct default authen‐
47 tication mechanism for users with stored SCRAM-SHA-1 and SCRAM-SHA-256
48 credentials:
49 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
51 /* the correct authMechanism is negotiated between the driver and server. */
52 Alternatively, SCRAM-SHA-256 can be explicitly specified as an auth‐
54 Mechanism.
55 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-256&authSource=mydb");
57 Passwords for SCRAM-SHA-256 undergo the preprocessing step known as
59 SASLPrep specified in RFC 4013. SASLPrep will only be performed for
60 passwords containing non-ASCII characters. SASLPrep requires libicu.
61 If libicu is not available, attempting to authenticate over
62 SCRAM-SHA-256 with non-ASCII passwords will result in error.
63 Usernames never undergo SASLPrep.
65 By default, when building the C driver libicu is linked if available.
67 This can be changed with the ENABLE_ICU cmake option. To specify an in‐
68 stallation path of libicu, specify ICU_ROOT as a cmake option. See the
69 FindICU documentation for more information.
70
72 The default authentication mechanism before MongoDB 4.0 is SCRAM-SHA-1
73 (RFC 5802). Using this authentication mechanism means that the password
74 is never actually sent over the wire when authenticating, but rather a
75 computed proof that the client password is the same as the password the
76 server knows.
77 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-1&authSource=mydb");
79 NOTE:
81 SCRAM-SHA-1 authenticates against the admin database by default. If
82 the user is created in another database, then specifying the auth‐
83 Source is required.
84
86 The MONGODB-CR authMechanism is deprecated and will no longer function
87 in MongoDB 4.0. Instead, specify no authMechanism and the driver will
88 use an authentication mechanism compatible with your server.
89
91 NOTE:
92 On UNIX-like environments, Kerberos support requires compiling the
93 driver against cyrus-sasl.
94 On Windows, Kerberos support requires compiling the driver against
96 Windows Native SSPI or cyrus-sasl. The default configuration of the
97 driver will use Windows Native SSPI.
98 To modify the default configuration, use the cmake option EN‐
100 ABLE_SASL.
101 GSSAPI (Kerberos) authentication is available in the Enterprise Edition
103 of MongoDB. To authenticate using GSSAPI, the MongoDB C driver must be
104 installed with SASL support.
105 On UNIX-like environments, run the kinit command before using the fol‐
107 lowing authentication methods:
108 $ kinit mongodbuser@EXAMPLE.COM
110 mongodbuser@EXAMPLE.COM's Password:
111 $ klistCredentials cache: FILE:/tmp/krb5cc_1000
112 Principal: mongodbuser@EXAMPLE.COM
113 Issued Expires Principal
115 Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/EXAMPLE.COM@EXAMPLE.COM
116 Now authenticate using the MongoDB URI. GSSAPI authenticates against
118 the $external virtual database, so a database does not need to be spec‐
119 ified in the URI. Note that the Kerberos principal must be URL-encoded:
120 mongoc_client_t *client;
122 client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI");
124 NOTE:
126 GSSAPI authenticates against the $external database, so specifying
127 the authSource database is not required.
128 The driver supports these GSSAPI properties:
130 • CANONICALIZE_HOST_NAME: This might be required with Cyrus-SASL when
132 the hosts report different hostnames than what is used in the Ker‐
133 beros database. The default is "false".
134 • SERVICE_NAME: Use a different service name than the default, "mon‐
136 godb".
137 Set properties in the URL:
139 mongoc_client_t *client;
141 client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI&"
143 "authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");
144 If you encounter errors such as Invalid net address, check if the ap‐
146 plication is behind a NAT (Network Address Translation) firewall. If
147 so, create a ticket that uses forwardable and addressless Kerberos
148 tickets. This can be done by passing -f -A to kinit.
149 $ kinit -f -A mongodbuser@EXAMPLE.COM
151
153 NOTE:
154 The MongoDB C Driver must be compiled with SASL support in order to
155 use SASL PLAIN authentication.
156 MongoDB Enterprise Edition supports the SASL PLAIN authentication mech‐
158 anism, initially intended for delegating authentication to an LDAP
159 server. Using the SASL PLAIN mechanism is very similar to the challenge
160 response mechanism with usernames and passwords. This authentication
161 mechanism uses the $external virtual database for LDAP support:
162 NOTE:
164 SASL PLAIN is a clear-text authentication mechanism. It is strongly
165 recommended to connect to MongoDB using TLS with certificate valida‐
166 tion when using the PLAIN mechanism.
167 mongoc_client_t *client;
169 client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN");
171 PLAIN authenticates against the $external database, so specifying the
173 authSource database is not required.
174
176 NOTE:
177 The MongoDB C Driver must be compiled with TLS support for X.509 au‐
178 thentication support. Once this is done, start a server with the
179 following options:
180 $ mongod --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
182 The MONGODB-X509 mechanism authenticates a username derived from the
184 distinguished subject name of the X.509 certificate presented by the
185 driver during TLS negotiation. This authentication method requires the
186 use of TLS connections with certificate validation.
187 mongoc_client_t *client;
189 mongoc_ssl_opt_t ssl_opts = { 0 };
190 ssl_opts.pem_file = "mycert.pem";
192 ssl_opts.pem_pwd = "mycertpassword";
193 ssl_opts.ca_file = "myca.pem";
194 ssl_opts.ca_dir = "trust_dir";
195 ssl_opts.weak_cert_validation = false;
196 client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
198 mongoc_client_set_ssl_opts (client, &ssl_opts);
199 MONGODB-X509 authenticates against the $external database, so specify‐
201 ing the authSource database is not required. For more information on
202 the x509_derived_username, see the MongoDB server x.509 tutorial.
203 NOTE:
205 The MongoDB C Driver will attempt to determine the x509 derived
206 username when none is provided, and as of MongoDB 3.4 providing the
207 username is not required at all.
208
210 The MONGODB-AWS mechanism authenticates to MongoDB servers with creden‐
211 tials provided by AWS Identity and Access Management (IAM).
212 To authenticate, create a user with an associated Amazon Resource Name
214 (ARN) on the $external database, and specify the MONGODB-AWS authMecha‐
215 nism in the URI.
216 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost/?authMechanism=MONGODB-AWS");
218 Since MONGODB-AWS always authenticates against the $external database,
220 so specifying the authSource database is not required.
221 Credentials include the access key id, secret access key, and optional
223 session token. They may be obtained from the following ways.
224 AWS credentials via URI
226 Credentials may be passed directly in the URI as username/password.
227 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS");
229 This may include a session token passed with authMechanismProperties.
231 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");
233 AWS credentials via environment
235 If credentials are not passed through the URI, libmongoc will check for
236 the following environment variables.
237 • AWS_ACCESS_KEY_ID
239 • AWS_SECRET_ACCESS_KEY
241 • AWS_SESSION_TOKEN (optional)
243 AWS Credentials via ECS
245 If credentials are not passed in the URI or with environment variables,
246 libmongoc will check if the environment variable AWS_CONTAINER_CREDEN‐
247 TIALS_RELATIVE_URI is set, and if so, attempt to retrieve temporary
248 credentials from the ECS task metadata by querying a link local ad‐
249 dress.
250 AWS Credentials via EC2
252 If credentials are not passed in the URI or with environment variables,
253 and the environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is
254 not set, libmongoc will attempt to retrieve temporary credentials from
255 the EC2 machine metadata by querying link local addresses.
256
258 MongoDB, Inc
259
261 2017-present, MongoDB, Inc
2621.24.3 Aug 17, 2023 MONGOC_AUTHENTICATION(3)