1MONGOC_AUTHENTICATION(3) libmongoc MONGOC_AUTHENTICATION(3)
2This guide covers the use of authentication options with the MongoDB C Driver.
6Ensure that the MongoDB server is also properly configured for authentication
7before making a connection. For more information, see the MongoDB security
9The MongoDB C driver supports several authentication mechanisms through the
11use of MongoDB connection URIs.
12By default, if a username and password are provided as part of the connection
14string (and an optional authentication database), they are used to connect via
15the default authentication mechanism of the server.
16To select a specific authentication mechanism other than the default, see the
18list of supported mechanism below.
19 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
21 Currently supported values for the authMechanism connection string op‐
23 tion are:
24 • SCRAM-SHA-1
26 • MONGODB-CR (deprecated)
28 • GSSAPI
30 • PLAIN
32 • X509
34 • MONGODB-AWS
36
38 MongoDB 4.0 introduces support for authenticating using the SCRAM pro‐
39 tocol with the more secure SHA-256 hash described in RFC 7677. Using
40 this authentication mechanism means that the password is never actually
41 sent over the wire when authenticating, but rather a computed proof
42 that the client password is the same as the password the server knows.
43 In MongoDB 4.0, the C driver can determine the correct default authen‐
44 tication mechanism for users with stored SCRAM-SHA-1 and SCRAM-SHA-256
45 credentials:
46 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
48 /* the correct authMechanism is negotiated between the driver and server. */
49 Alternatively, SCRAM-SHA-256 can be explicitly specified as an auth‐
51 Mechanism.
52 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-256&authSource=mydb");
54
56 The default authentication mechanism before MongoDB 4.0 is SCRAM-SHA-1
57 (RFC 5802). Using this authentication mechanism means that the password
58 is never actually sent over the wire when authenticating, but rather a
59 computed proof that the client password is the same as the password the
60 server knows.
61 mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-1&authSource=mydb");
63 NOTE:
65 SCRAM-SHA-1 authenticates against the admin database by default. If
66 the user is created in another database, then specifying the auth‐
67 Source is required.
68
70 The MONGODB-CR authMechanism is deprecated and will no longer function
71 in MongoDB 4.0. Instead, specify no authMechanism and the driver will
72 use an authentication mechanism compatible with your server.
73
75 NOTE:
76 On UNIX-like environments, Kerberos support requires compiling the
77 driver against cyrus-sasl.
78 On Windows, Kerberos support requires compiling the driver against
80 Windows Native SSPI or cyrus-sasl. The default configuration of the
81 driver will use Windows Native SSPI.
82 To modify the default configuration, use the cmake option EN‐
84 ABLE_SASL.
85 GSSAPI (Kerberos) authentication is available in the Enterprise Edition
87 of MongoDB. To authenticate using GSSAPI, the MongoDB C driver must be
88 installed with SASL support.
89 On UNIX-like environments, run the kinit command before using the fol‐
91 lowing authentication methods:
92 $ kinit mongodbuser@EXAMPLE.COM
94 mongodbuser@EXAMPLE.COM's Password:
95 $ klistCredentials cache: FILE:/tmp/krb5cc_1000
96 Principal: mongodbuser@EXAMPLE.COM
97 Issued Expires Principal
99 Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/EXAMPLE.COM@EXAMPLE.COM
100 Now authenticate using the MongoDB URI. GSSAPI authenticates against
102 the $external virtual database, so a database does not need to be spec‐
103 ified in the URI. Note that the Kerberos principal must be URL-encoded:
104 mongoc_client_t *client;
106 client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI");
108 NOTE:
110 GSSAPI authenticates against the $external database, so specifying
111 the authSource database is not required.
112 The driver supports these GSSAPI properties:
114 • CANONICALIZE_HOST_NAME: This might be required with Cyrus-SASL when
116 the hosts report different hostnames than what is used in the Ker‐
117 beros database. The default is "false".
118 • SERVICE_NAME: Use a different service name than the default, "mon‐
120 godb".
121 Set properties in the URL:
123 mongoc_client_t *client;
125 client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI&"
127 "authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");
128 If you encounter errors such as Invalid net address, check if the ap‐
130 plication is behind a NAT (Network Address Translation) firewall. If
131 so, create a ticket that uses forwardable and addressless Kerberos
132 tickets. This can be done by passing -f -A to kinit.
133 $ kinit -f -A mongodbuser@EXAMPLE.COM
135
137 NOTE:
138 The MongoDB C Driver must be compiled with SASL support in order to
139 use SASL PLAIN authentication.
140 MongoDB Enterprise Edition supports the SASL PLAIN authentication mech‐
142 anism, initially intended for delegating authentication to an LDAP
143 server. Using the SASL PLAIN mechanism is very similar to the challenge
144 response mechanism with usernames and passwords. This authentication
145 mechanism uses the $external virtual database for LDAP support:
146 NOTE:
148 SASL PLAIN is a clear-text authentication mechanism. It is strongly
149 recommended to connect to MongoDB using TLS with certificate valida‐
150 tion when using the PLAIN mechanism.
151 mongoc_client_t *client;
153 client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN");
155 PLAIN authenticates against the $external database, so specifying the
157 authSource database is not required.
158
160 NOTE:
161 The MongoDB C Driver must be compiled with TLS support for X.509 au‐
162 thentication support. Once this is done, start a server with the
163 following options:
164 $ mongod --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
166 The MONGODB-X509 mechanism authenticates a username derived from the
168 distinguished subject name of the X.509 certificate presented by the
169 driver during TLS negotiation. This authentication method requires the
170 use of TLS connections with certificate validation.
171 mongoc_client_t *client;
173 mongoc_ssl_opt_t ssl_opts = { 0 };
174 ssl_opts.pem_file = "mycert.pem";
176 ssl_opts.pem_pwd = "mycertpassword";
177 ssl_opts.ca_file = "myca.pem";
178 ssl_opts.ca_dir = "trust_dir";
179 ssl_opts.weak_cert_validation = false;
180 client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
182 mongoc_client_set_ssl_opts (client, &ssl_opts);
183 MONGODB-X509 authenticates against the $external database, so specify‐
185 ing the authSource database is not required. For more information on
186 the x509_derived_username, see the MongoDB server x.509 tutorial.
187 NOTE:
189 The MongoDB C Driver will attempt to determine the x509 derived
190 username when none is provided, and as of MongoDB 3.4 providing the
191 username is not required at all.
192
194 The MONGODB-AWS mechanism authenticates to MongoDB servers with creden‐
195 tials provided by AWS Identity and Access Management (IAM).
196 To authenticate, create a user with an associated Amazon Resource Name
198 (ARN) on the $external database, and specify the MONGODB-AWS authMecha‐
199 nism in the URI.
200 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost/?authMechanism=MONGODB-AWS");
202 Since MONGODB-AWS always authenticates against the $external database,
204 so specifying the authSource database is not required.
205 Credentials include the access key id, secret access key, and optional
207 session token. They may be obtained from the following ways.
208 AWS credentials via URI
210 Credentials may be passed directly in the URI as username/password.
211 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS");
213 This may include a session token passed with authMechanismProperties.
215 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");
217 AWS credentials via environment
219 If credentials are not passed through the URI, libmongoc will check for
220 the following environment variables.
221 • AWS_ACCESS_KEY_ID
223 • AWS_SECRET_ACCESS_KEY
225 • AWS_SESSION_TOKEN (optional)
227 AWS Credentials via ECS
229 If credentials are not passed in the URI or with environment variables,
230 libmongoc will check if the environment variable AWS_CONTAINER_CREDEN‐
231 TIALS_RELATIVE_URI is set, and if so, attempt to retrieve temporary
232 credentials from the ECS task metadata by querying a link local ad‐
233 dress.
234 AWS Credentials via EC2
236 If credentials are not passed in the URI or with environment variables,
237 and the environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is
238 not set, libmongoc will attempt to retrieve temporary credentials from
239 the EC2 machine metadata by querying link local addresses.
240
242 MongoDB, Inc
243
245 2017-present, MongoDB, Inc
2461.25.1 Nov 08, 2023 MONGOC_AUTHENTICATION(3)