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          On UNIX-like environments, Kerberos support requires  compiling  the
93          driver against cyrus-sasl.
94
95          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
99          To  modify  the  default  configuration,  use  the  cmake option EN‐
100          ABLE_SASL.
101
102       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
106       On UNIX-like environments, run the kinit command before using the  fol‐
107       lowing authentication methods:
108
109          $ kinit mongodbuser@EXAMPLE.COM
110          mongodbuser@EXAMPLE.COM's Password:
111          $ klistCredentials cache: FILE:/tmp/krb5cc_1000
112                  Principal: mongodbuser@EXAMPLE.COM
113
114            Issued                Expires               Principal
115          Feb  9 13:48:51 2013  Feb  9 23:48:51 2013  krbtgt/EXAMPLE.COM@EXAMPLE.COM
116
117       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
121          mongoc_client_t *client;
122
123          client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI");
124
125       NOTE:
126          GSSAPI  authenticates  against the $external database, so specifying
127          the authSource database is not required.
128
129       The driver supports these GSSAPI properties:
130
131CANONICALIZE_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
135SERVICE_NAME: Use a different service name than  the  default,  "mon‐
136         godb".
137
138       Set properties in the URL:
139
140          mongoc_client_t *client;
141
142          client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI&"
143                                      "authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");
144
145       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
150          $ kinit -f -A mongodbuser@EXAMPLE.COM
151

SASL PLAIN AUTHENTICATION

153       NOTE:
154          The MongoDB C Driver must be compiled with SASL support in order  to
155          use SASL PLAIN authentication.
156
157       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
163       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
168          mongoc_client_t *client;
169
170          client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN");
171
172       PLAIN  authenticates  against the $external database, so specifying the
173       authSource database is not required.
174

X.509 CERTIFICATE AUTHENTICATION

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
181              $ mongod --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
182
183       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
188          mongoc_client_t *client;
189          mongoc_ssl_opt_t ssl_opts = { 0 };
190
191          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
197          client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
198          mongoc_client_set_ssl_opts (client, &ssl_opts);
199
200       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
204       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

AUTHENTICATION VIA AWS IAM

210       The MONGODB-AWS mechanism authenticates to MongoDB servers with creden‐
211       tials provided by AWS Identity and Access Management (IAM).
212
213       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
217          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost/?authMechanism=MONGODB-AWS");
218
219       Since MONGODB-AWS always authenticates against the $external  database,
220       so specifying the authSource database is not required.
221
222       Credentials  include the access key id, secret access key, and optional
223       session token. They may be obtained from the following ways.
224
225   AWS credentials via URI
226       Credentials may be passed directly in the URI as username/password.
227
228          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS");
229
230       This may include a session token passed with authMechanismProperties.
231
232          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://<access key id>:<secret access key>localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");
233
234   AWS credentials via environment
235       If credentials are not passed through the URI, libmongoc will check for
236       the following environment variables.
237
238       • AWS_ACCESS_KEY_ID
239
240       • AWS_SECRET_ACCESS_KEY
241
242       • AWS_SESSION_TOKEN (optional)
243
244   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
251   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

AUTHOR

258       MongoDB, Inc
259
261       2017-present, MongoDB, Inc
262
263
264
265
2661.23.1                           Oct 20, 2022         MONGOC_AUTHENTICATION(3)
Impressum