1MONGOC_AUTHENTICATION(3)           libmongoc          MONGOC_AUTHENTICATION(3)
2
3
4

NAME

6       mongoc_authentication - Authentication
7
8       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
13       The MongoDB C driver supports several authentication mechanisms through
14       the use of MongoDB connection URIs.
15
16       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
20       To  select  a specific authentication mechanism other than the default,
21       see the list of supported mechanism below.
22
23          mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
24
25       Currently supported values for the authMechanism connection string  op‐
26       tion are:
27
28SCRAM-SHA-1
29
30MONGODB-CR (deprecated)
31
32GSSAPI
33
34PLAIN
35
36X509
37
38MONGODB-AWS
39

BASIC AUTHENTICATION (SCRAM-SHA-256)

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
50          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
53       Alternatively, SCRAM-SHA-256 can be explicitly specified  as  an  auth‐
54       Mechanism.
55
56          mongoc_client_t *client =  mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-256&authSource=mydb");
57
58       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
64       Usernames never undergo SASLPrep.
65
66       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

BASIC AUTHENTICATION (SCRAM-SHA-1)

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
78          mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-1&authSource=mydb");
79
80       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

LEGACY AUTHENTICATION (MONGODB-CR)

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

GSSAPI (KERBEROS) AUTHENTICATION

91       NOTE:
92          Kerberos support requires compiling the driver against cyrus-sasl on
93          UNIX-like  environments.  On  Windows, configure the driver to build
94          against the Windows Native SSPI.
95
96       GSSAPI (Kerberos) authentication is available in the Enterprise Edition
97       of  MongoDB. To authenticate using GSSAPI, the MongoDB C driver must be
98       installed with SASL support.
99
100       On UNIX-like environments, run the kinit command before using the  fol‐
101       lowing authentication methods:
102
103          $ kinit mongodbuser@EXAMPLE.COM
104          mongodbuser@EXAMPLE.COM's Password:
105          $ klistCredentials cache: FILE:/tmp/krb5cc_1000
106                  Principal: mongodbuser@EXAMPLE.COM
107
108            Issued                Expires               Principal
109          Feb  9 13:48:51 2013  Feb  9 23:48:51 2013  krbtgt/EXAMPLE.COM@EXAMPLE.COM
110
111       Now  authenticate  using  the MongoDB URI. GSSAPI authenticates against
112       the $external virtual database, so a database does not need to be spec‐
113       ified in the URI. Note that the Kerberos principal must be URL-encoded:
114
115          mongoc_client_t *client;
116
117          client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI");
118
119       NOTE:
120          GSSAPI  authenticates  against the $external database, so specifying
121          the authSource database is not required.
122
123       The driver supports these GSSAPI properties:
124
125CANONICALIZE_HOST_NAME: This might be required with  Cyrus-SASL  when
126         the  hosts  report  different hostnames than what is used in the Ker‐
127         beros database. The default is "false".
128
129SERVICE_NAME: Use a different service name than  the  default,  "mon‐
130         godb".
131
132       Set properties in the URL:
133
134          mongoc_client_t *client;
135
136          client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI&"
137                                      "authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");
138
139       If  you  encounter errors such as Invalid net address, check if the ap‐
140       plication is behind a NAT (Network Address  Translation)  firewall.  If
141       so,  create  a  ticket  that  uses forwardable and addressless Kerberos
142       tickets. This can be done by passing -f -A to kinit.
143
144          $ kinit -f -A mongodbuser@EXAMPLE.COM
145

SASL PLAIN AUTHENTICATION

147       NOTE:
148          The MongoDB C Driver must be compiled with SASL support in order  to
149          use SASL PLAIN authentication.
150
151       MongoDB Enterprise Edition supports the SASL PLAIN authentication mech‐
152       anism, initially intended for  delegating  authentication  to  an  LDAP
153       server. Using the SASL PLAIN mechanism is very similar to the challenge
154       response mechanism with usernames and  passwords.  This  authentication
155       mechanism uses the $external virtual database for LDAP support:
156
157       NOTE:
158          SASL  PLAIN is a clear-text authentication mechanism. It is strongly
159          recommended to connect to MongoDB using TLS with certificate valida‐
160          tion when using the PLAIN mechanism.
161
162          mongoc_client_t *client;
163
164          client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN");
165
166       PLAIN  authenticates  against the $external database, so specifying the
167       authSource database is not required.
168

X.509 CERTIFICATE AUTHENTICATION

170       NOTE:
171          The MongoDB C Driver must be compiled with TLS support for X.509 au‐
172          thentication  support.  Once  this  is done, start a server with the
173          following options:
174
175              $ mongod --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
176
177       The MONGODB-X509 mechanism authenticates a username  derived  from  the
178       distinguished  subject  name  of the X.509 certificate presented by the
179       driver during TLS negotiation. This authentication method requires  the
180       use of TLS connections with certificate validation.
181
182          mongoc_client_t *client;
183          mongoc_ssl_opt_t ssl_opts = { 0 };
184
185          ssl_opts.pem_file = "mycert.pem";
186          ssl_opts.pem_pwd = "mycertpassword";
187          ssl_opts.ca_file = "myca.pem";
188          ssl_opts.ca_dir = "trust_dir";
189          ssl_opts.weak_cert_validation = false;
190
191          client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
192          mongoc_client_set_ssl_opts (client, &ssl_opts);
193
194       MONGODB-X509  authenticates against the $external database, so specify‐
195       ing the authSource database is not required. For  more  information  on
196       the x509_derived_username, see the MongoDB server x.509 tutorial.
197
198       NOTE:
199          The  MongoDB  C  Driver  will  attempt to determine the x509 derived
200          username when none is provided, and as of MongoDB 3.4 providing  the
201          username is not required at all.
202

AUTHENTICATION VIA AWS IAM

204       The MONGODB-AWS mechanism authenticates to MongoDB servers with creden‐
205       tials provided by AWS Identity and Access Management (IAM).
206
207       To authenticate, create a user with an associated Amazon Resource  Name
208       (ARN) on the $external database, and specify the MONGODB-AWS authMecha‐
209       nism in the URI.
210
211          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost/?authMechanism=MONGODB-AWS");
212
213       Since MONGODB-AWS always authenticates against the $external  database,
214       so specifying the authSource database is not required.
215
216       Credentials  include the access key id, secret access key, and optional
217       session token. They may be obtained from the following ways.
218
219   AWS credentials via URI
220       Credentials may be passed directly in the URI as username/password.
221
222          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS");
223
224       This may include a session token passed with authMechanismProperties.
225
226          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");
227
228   AWS credentials via environment
229       If credentials are not passed through the URI, libmongoc will check for
230       the following environment variables.
231
232       • AWS_ACCESS_KEY_ID
233
234       • AWS_SECRET_ACCESS_KEY
235
236       • AWS_SESSION_TOKEN (optional)
237
238   AWS Credentials via ECS
239       If credentials are not passed in the URI or with environment variables,
240       libmongoc will check if the environment variable  AWS_CONTAINER_CREDEN‐
241       TIALS_RELATIVE_URI  is  set,  and  if so, attempt to retrieve temporary
242       credentials from the ECS task metadata by querying  a  link  local  ad‐
243       dress.
244
245   AWS Credentials via EC2
246       If credentials are not passed in the URI or with environment variables,
247       and the environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI  is
248       not  set, libmongoc will attempt to retrieve temporary credentials from
249       the EC2 machine metadata by querying link local addresses.
250

AUTHOR

252       MongoDB, Inc
253
255       2017-present, MongoDB, Inc
256
257
258
259
2601.20.0                           Nov 18, 2021         MONGOC_AUTHENTICATION(3)
Impressum