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
26 option are:
27 · SCRAM-SHA-1
29 · MONGODB-CR (deprecated)
31 · GSSAPI
33 · PLAIN
35 · X509
37
39 MongoDB 4.0 introduces support for authenticating using the SCRAM pro‐
40 tocol with the more secure SHA-256 hash described in RFC 7677. Using
41 this authentication mechanism means that the password is never actually
42 sent over the wire when authenticating, but rather a computed proof
43 that the client password is the same as the password the server knows.
44 In MongoDB 4.0, the C driver can determine the correct default authen‐
45 tication mechanism for users with stored SCRAM-SHA-1 and SCRAM-SHA-256
46 credentials:
47 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
49 /* the correct authMechanism is negotiated between the driver and server. */
50 Alternatively, SCRAM-SHA-256 can be explicitly specified as an auth‐
52 Mechanism.
53 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-256&authSource=mydb");
55 Passwords for SCRAM-SHA-256 undergo the preprocessing step known as
57 SASLPrep specified in RFC 4013. SASLPrep will only be performed for
58 passwords containing non-ASCII characters. SASLPrep requires libicu.
59 If libicu is not available, attempting to authenticate over
60 SCRAM-SHA-256 with non-ASCII passwords will result in error.
61 Usernames never undergo SASLPrep.
63 By default, when building the C driver libicu is linked if available.
65 This can be changed with the ENABLE_ICU cmake option. To specify an
66 installation path of libicu, specify ICU_ROOT as a cmake option. See
67 the FindICU documentation for more information.
68
70 The default authentication mechanism before MongoDB 4.0 is SCRAM-SHA-1
71 (RFC 5802). Using this authentication mechanism means that the password
72 is never actually sent over the wire when authenticating, but rather a
73 computed proof that the client password is the same as the password the
74 server knows.
75 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-1&authSource=mydb");
77 NOTE:
79 SCRAM-SHA-1 authenticates against the admin database by default. If
80 the user is created in another database, then specifying the auth‐
81 Source is required.
82
84 The MONGODB-CR authMechanism is deprecated and will no longer function
85 in MongoDB 4.0. Instead, specify no authMechanism and the driver will
86 use an authentication mechanism compatible with your server.
87
89 NOTE:
90 Kerberos support requires compiling the driver against cyrus-sasl on
91 UNIX-like environments. On Windows, configure the driver to build
92 against the Windows Native SSPI.
93 GSSAPI (Kerberos) authentication is available in the Enterprise Edition
95 of MongoDB. To authenticate using GSSAPI, the MongoDB C driver must be
96 installed with SASL support.
97 On UNIX-like environments, run the kinit command before using the fol‐
99 lowing authentication methods:
100 $ kinit mongodbuser@EXAMPLE.COM
102 mongodbuser@EXAMPLE.COM's Password:
103 $ klistCredentials cache: FILE:/tmp/krb5cc_1000
104 Principal: mongodbuser@EXAMPLE.COM
105 Issued Expires Principal
107 Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/EXAMPLE.COM@EXAMPLE.COM
108 Now authenticate using the MongoDB URI. GSSAPI authenticates against
110 the $external virtual database, so a database does not need to be spec‐
111 ified in the URI. Note that the Kerberos principal must be URL-encoded:
112 mongoc_client_t *client;
114 client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI");
116 NOTE:
118 GSSAPI authenticates against the $external database, so specifying
119 the authSource database is not required.
120 The driver supports these GSSAPI properties:
122 · CANONICALIZE_HOST_NAME: This might be required with Cyrus-SASL when
124 the hosts report different hostnames than what is used in the Ker‐
125 beros database. The default is "false".
126 · SERVICE_NAME: Use a different service name than the default, "mon‐
128 godb".
129 Set properties in the URL:
131 mongoc_client_t *client;
133 client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI&"
135 "authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");
136 If you encounter errors such as Invalid net address, check if the
138 application is behind a NAT (Network Address Translation) firewall. If
139 so, create a ticket that uses forwardable and addressless Kerberos
140 tickets. This can be done by passing -f -A to kinit.
141 $ kinit -f -A mongodbuser@EXAMPLE.COM
143
145 NOTE:
146 The MongoDB C Driver must be compiled with SASL support in order to
147 use SASL PLAIN authentication.
148 MongoDB Enterprise Edition supports the SASL PLAIN authentication mech‐
150 anism, initially intended for delegating authentication to an LDAP
151 server. Using the SASL PLAIN mechanism is very similar to the challenge
152 response mechanism with usernames and passwords. This authentication
153 mechanism uses the $external virtual database for LDAP support:
154 NOTE:
156 SASL PLAIN is a clear-text authentication mechanism. It is strongly
157 recommended to connect to MongoDB using SSL with certificate valida‐
158 tion when using the PLAIN mechanism.
159 mongoc_client_t *client;
161 client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN");
163 PLAIN authenticates against the $external database, so specifying the
165 authSource database is not required.
166
168 NOTE:
169 The MongoDB C Driver must be compiled with SSL support for X.509
170 authentication support. Once this is done, start a server with the
171 following options:
172 $ mongod --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile ca.pem
174 The MONGODB-X509 mechanism authenticates a username derived from the
176 distinguished subject name of the X.509 certificate presented by the
177 driver during SSL negotiation. This authentication method requires the
178 use of SSL connections with certificate validation.
179 mongoc_client_t *client;
181 mongoc_ssl_opt_t ssl_opts = { 0 };
182 ssl_opts.pem_file = "mycert.pem";
184 ssl_opts.pem_pwd = "mycertpassword";
185 ssl_opts.ca_file = "myca.pem";
186 ssl_opts.ca_dir = "trust_dir";
187 ssl_opts.weak_cert_validation = false;
188 client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
190 mongoc_client_set_ssl_opts (client, &ssl_opts);
191 MONGODB-X509 authenticates against the $external database, so specify‐
193 ing the authSource database is not required. For more information on
194 the x509_derived_username, see the MongoDB server x.509 tutorial.
195 NOTE:
197 The MongoDB C Driver will attempt to determine the x509 derived
198 username when none is provided, and as of MongoDB 3.4 providing the
199 username is not required at all.
200
202 MongoDB, Inc
203
205 2017-present, MongoDB, Inc
2061.16.2 Feb 25, 2020 MONGOC_AUTHENTICATION(3)