1MONGOC_AUTHENTICATION(3)       MongoDB C Driver       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
26       option are:
27
28       · SCRAM-SHA-1
29
30       · MONGODB-CR (deprecated)
31
32       · GSSAPI
33
34       · PLAIN
35
36       · X509
37

BASIC AUTHENTICATION (SCRAM-SHA-256)

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

BASIC AUTHENTICATION (SCRAM-SHA-1)

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

LEGACY AUTHENTICATION (MONGODB-CR)

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

GSSAPI (KERBEROS) AUTHENTICATION

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
94       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
98       On UNIX-like environments, run the kinit command before using the  fol‐
99       lowing authentication methods:
100
101          $ kinit mongodbuser@EXAMPLE.COM
102          mongodbuser@EXAMPLE.COM's Password:
103          $ klistCredentials cache: FILE:/tmp/krb5cc_1000
104                  Principal: mongodbuser@EXAMPLE.COM
105
106            Issued                Expires               Principal
107          Feb  9 13:48:51 2013  Feb  9 23:48:51 2013  krbtgt/EXAMPLE.COM@EXAMPLE.COM
108
109       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
113          mongoc_client_t *client;
114
115          client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI");
116
117       NOTE:
118          GSSAPI  authenticates  against the $external database, so specifying
119          the authSource database is not required.
120
121       The driver supports these GSSAPI properties:
122
123       · 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
127       · SERVICE_NAME: Use a different service name than  the  default,  "mon‐
128         godb".
129
130       Set properties in the URL:
131
132          mongoc_client_t *client;
133
134          client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@mongo-server.example.com/?authMechanism=GSSAPI&"
135                                      "authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");
136
137       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
142          $ kinit -f -A mongodbuser@EXAMPLE.COM
143

SASL PLAIN AUTHENTICATION

145       NOTE:
146          The MongoDB C Driver must be compiled with SASL support in order  to
147          use SASL PLAIN authentication.
148
149       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
155       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
160          mongoc_client_t *client;
161
162          client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN");
163
164       PLAIN  authenticates  against the $external database, so specifying the
165       authSource database is not required.
166

X.509 CERTIFICATE AUTHENTICATION

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
173              $ mongod --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile ca.pem
174
175       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
180          mongoc_client_t *client;
181          mongoc_ssl_opt_t ssl_opts = { 0 };
182
183          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
189          client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
190          mongoc_client_set_ssl_opts (client, &ssl_opts);
191
192       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
196       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

AUTHOR

202       MongoDB, Inc
203
205       2017-present, MongoDB, Inc
206
207
208
209
2101.14.0                           Feb 22, 2019         MONGOC_AUTHENTICATION(3)
Impressum