Skip to content

Commit 72e466a

Browse files
rustagirrustagir
authored
DOCSP-37872: auth (#21)
1 parent 9bb4110 commit 72e466a

File tree

2 files changed

+333
-0
lines changed

2 files changed

+333
-0
lines changed

‎source/tutorials/connect.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Connect to MongoDB
77
.. toctree::
88

99
/tutorials/connect/tls/
10+
/tutorials/connect/auth/
1011

1112
.. contents:: On this page
1213
:local:

‎source/tutorials/connect/auth.txt

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
.. _javars-auth:
2+
3+
==============
4+
Authentication
5+
==============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
The driver supports all MongoDB authentication mechanisms,
14+
including those available only in the MongoDB Enterprise Edition.
15+
16+
MongoCredential
17+
---------------
18+
19+
Include the following import statements:
20+
21+
.. code-block:: java
22+
23+
import com.mongodb.MongoCredential;
24+
import com.mongodb.ConnectionString;
25+
import com.mongodb.reactivestreams.client.MongoClients;
26+
import com.mongodb.reactivestreams.client.MongoClient;
27+
28+
An authentication credential is represented as an instance of the
29+
``MongoCredential`` class. The ``MongoCredential`` class includes
30+
static factory methods for each of the supported authentication
31+
mechanisms.
32+
33+
Default Authentication Mechanism
34+
--------------------------------
35+
36+
In MongoDB 3.0, MongoDB changed the default authentication mechanism
37+
from ``MONGODB-CR`` to ``SCRAM-SHA-1``. In MongoDB 4.0, support for
38+
the deprecated ``MONGODB-CR`` mechanism was removed and ``SCRAM-
39+
SHA-256`` support was added.
40+
41+
To create a credential that authenticates by using the default
42+
authentication mechanism, regardless of server version, create a
43+
credential by using the ``createCredential()`` static factory method:
44+
45+
.. code-block:: java
46+
47+
String user; // the user name
48+
String source; // the source where the user is defined
49+
char[] password; // the password as a character array
50+
// ...
51+
MongoCredential credential = MongoCredential.createCredential(user, source, password);
52+
53+
MongoClient mongoClient = MongoClients.create(
54+
MongoClientSettings.builder()
55+
.applyToClusterSettings(builder ->
56+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
57+
.credential(credential)
58+
.build());
59+
60+
Or, you can use a connection string without explicitly specifying the
61+
authentication mechanism:
62+
63+
.. code-block:: java
64+
65+
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1");
66+
67+
For challenge and response mechanisms, using the default
68+
authentication mechanism is the recommended approach, as it makes
69+
upgrading from MongoDB 2.6 to MongoDB 3.0 more simple, even after
70+
upgrading the authentication schema. For MongoDB 4.0 users, using the
71+
default authentication mechanism is also recommended as the mechanisms are
72+
checked and the correct hashing algorithm is used.
73+
74+
SCRAM-Based Mechanisms
75+
----------------------
76+
77+
Salted Challenge-Response Authentication Mechanism (``SCRAM``) has been
78+
the default authentication mechanism for MongoDB since 3.0. ``SCRAM`` is
79+
based on the `IETF RFC 5802
80+
<https://datatracker.ietf.org/doc/html/rfc5802>`__ standard that defines
81+
best practices for implementation of challenge-response mechanisms for authenticating
82+
users with passwords.
83+
84+
MongoDB 3.0 introduced support for ``SCRAM-SHA-1``, which uses the
85+
``SHA-1`` hashing function. MongoDB 4.0 introduced support for ``SCRAM-
86+
SHA-256`` which uses the ``SHA-256`` hashing function.
87+
88+
SCRAM-SHA-256
89+
~~~~~~~~~~~~~
90+
91+
Using this mechanism requires MongoDB 4.0 and
92+
``featureCompatibilityVersion`` to be set to 4.0.
93+
94+
To explicitly create a credential of type ``SCRAM-SHA-256``, use
95+
the ``createScramSha256Credential()`` method:
96+
97+
.. code-block:: java
98+
99+
String user; // the user name
100+
String source; // the source where the user is defined
101+
char[] password; // the password as a character array
102+
// ...
103+
MongoCredential credential = MongoCredential.createScramSha256Credential(user, source, password);
104+
105+
MongoClient mongoClient = MongoClients.create(
106+
MongoClientSettings.builder()
107+
.applyToClusterSettings(builder ->
108+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
109+
.credential(credential)
110+
.build());
111+
112+
Or, you can use a connection string that explicitly specifies
113+
``authMechanism=SCRAM-SHA-256``:
114+
115+
.. code-block:: java
116+
117+
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-256");
118+
119+
SCRAM-SHA-1
120+
~~~~~~~~~~~
121+
122+
To explicitly create a credential of type ``SCRAM-SHA-1``, use the
123+
``createScramSha1Credential()`` method:
124+
125+
.. code-block:: java
126+
127+
String user; // the user name
128+
String source; // the source where the user is defined
129+
char[] password; // the password as a character array
130+
// ...
131+
MongoCredential credential = MongoCredential.createScramSha1Credential(user, source, password);
132+
133+
MongoClient mongoClient = MongoClients.create(
134+
MongoClientSettings.builder()
135+
.applyToClusterSettings(builder ->
136+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
137+
.credential(credential)
138+
.build());
139+
140+
Or, you can use a connection string that explicitly specifies
141+
``authMechanism=SCRAM-SHA-1``:
142+
143+
144+
.. code-block:: java
145+
146+
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1");
147+
148+
MONGODB-CR
149+
----------
150+
151+
.. important::
152+
153+
Starting in version 4.0, MongoDB removes support for the deprecated
154+
MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism.
155+
156+
If your deployment has user credentials stored in a ``MONGODB-CR`` schema,
157+
you must upgrade to use a ``SCRAM``-based mechanism before you
158+
upgrade to version 4.0.
159+
160+
To explicitly create a credential of type ``MONGODB-CR`` use the
161+
``createMongCRCredential()`` static factory method:
162+
163+
.. code-block:: java
164+
165+
String user; // the user name
166+
String database; // the name of the database in which the user is defined
167+
char[] password; // the password as a character array
168+
// ...
169+
MongoCredential credential = MongoCredential.createMongoCRCredential(user, database, password);
170+
171+
MongoClient mongoClient = MongoClients.create(
172+
MongoClientSettings.builder()
173+
.applyToClusterSettings(builder ->
174+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
175+
.credential(credential)
176+
.build());
177+
178+
Or, you can use a connection string that explicitly specifies
179+
``authMechanism=MONGODB-CR``:
180+
181+
.. code-block:: java
182+
183+
MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR");
184+
185+
.. note::
186+
187+
After you upgrade the authentication schema from ``MONGODB-CR`` to ``SCRAM``,
188+
``MONGODB-CR`` credentials will fail to authenticate.
189+
190+
X.509
191+
-----
192+
193+
With the ``X.509`` mechanism, MongoDB uses the X.509 certificate presented
194+
during SSL negotiation to authenticate a user whose name is derived
195+
from the distinguished name of the X.509 certificate.
196+
197+
X.509 authentication requires the use of SSL connections with
198+
certificate validation. To create a credential of this type use the
199+
``createMongoX509Credential()`` static factory method:
200+
201+
.. code-block:: java
202+
203+
String user; // The X.509 certificate derived user name, e.g. "CN=user,OU=OrgUnit,O=myOrg,..."
204+
// ...
205+
MongoCredential credential = MongoCredential.createMongoX509Credential(user);
206+
207+
MongoClient mongoClient = MongoClients.create(
208+
MongoClientSettings.builder()
209+
.applyToClusterSettings(builder ->
210+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
211+
.credential(credential)
212+
.build());
213+
214+
Or, you can use a connection string that explicitly specifies
215+
``authMechanism=MONGODB-X509``:
216+
217+
.. code-block:: java
218+
219+
MongoClient mongoClient = MongoClients.create("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&ssl=true");
220+
221+
See the :manual:`Use x.509 Certificates to Authenticate Clients </tutorial/configure-x509-client-authentication/>`
222+
tutorial in the Server manual to learn more about
223+
determining the subject name from the certificate.
224+
225+
Kerberos (GSSAPI)
226+
-----------------
227+
228+
MongoDB Enterprise supports proxy authentication through the Kerberos
229+
service. To create a credential of type Kerberos (GSSAPI), use the
230+
``createGSSAPICredential()`` static factory method:
231+
232+
.. code-block:: java
233+
234+
String user; // The Kerberos user name, including the realm, e.g. "[email protected]"
235+
// ...
236+
MongoCredential credential = MongoCredential.createGSSAPICredential(user);
237+
238+
MongoClient mongoClient = MongoClients.create(
239+
MongoClientSettings.builder()
240+
.applyToClusterSettings(builder ->
241+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
242+
.credential(credential)
243+
.build());
244+
245+
Or, you can use a connection string that explicitly specifies
246+
``authMechanism=GSSAPI``:
247+
248+
.. code-block:: java
249+
250+
MongoClient mongoClient = MongoClients.create("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI");
251+
252+
.. note::
253+
254+
The method refers to the ``GSSAPI`` authentication mechanism instead of
255+
``Kerberos`` because the driver authenticates by using the ``GSSAPI`` SASL mechanism.
256+
257+
To successfully authenticate by using Kerberos, the application typically
258+
must specify several system properties so that the underlying GSSAPI
259+
Java libraries can acquire a Kerberos ticket:
260+
261+
.. code-block:: none
262+
263+
java.security.krb5.realm=MYREALM.ME
264+
java.security.krb5.kdc=mykdc.myrealm.me
265+
266+
Depending on the Kerberos setup, additional property specifications
267+
might be required, either within the application code or, in some cases,
268+
by using the ``withMechanismProperty()`` method of the ``MongoCredential``
269+
instance:
270+
271+
- ``SERVICE_NAME``
272+
- ``CANONICALIZE_HOST_NAME``
273+
- ``JAVA_SUBJECT``
274+
- ``JAVA_SASL_CLIENT_PROPERTIES``
275+
276+
The following code shows how to specify the ``SERVICE_NAME`` property within the
277+
``MongoCredential`` object:
278+
279+
.. code-block:: java
280+
281+
credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "othername");
282+
283+
Or, you can specify the ``SERVICE_NAME`` property within the ``ConnectionString``:
284+
285+
.. code-block:: java
286+
287+
uri = "mongodb://username%40MYREALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername"
288+
289+
.. note::
290+
291+
On Windows, Oracles JRE uses `LSA
292+
<https://msdn.microsoft.com/en-us/library/windows/desktop/aa378326.aspx>`__
293+
rather than `SSPI
294+
<https://msdn.microsoft.com/en-us/library/windows/desktop/aa380493.aspx>`__
295+
in its implementation of GSSAPI, which limits interoperability with Windows
296+
Active Directory and in particular the ability to implement single
297+
sign-on.
298+
299+
LDAP (PLAIN)
300+
------------
301+
302+
MongoDB Enterprise supports proxy authentication through a
303+
Lightweight Directory Access Protocol (LDAP) service. To create a
304+
credential of type ``LDAP`` use the ``createPlainCredential()`` static
305+
factory method:
306+
307+
.. code-block:: java
308+
309+
String user; // The LDAP user name
310+
char[] password; // The LDAP password
311+
// ...
312+
MongoCredential credential = MongoCredential.createPlainCredential(user, "$external", password);
313+
314+
MongoClient mongoClient = MongoClients.create(
315+
MongoClientSettings.builder()
316+
.applyToClusterSettings(builder ->
317+
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
318+
.credential(credential)
319+
.build());
320+
321+
Or, you can use a connection string that explicitly specifies
322+
``authMechanism=PLAIN``:
323+
324+
.. code-block:: java
325+
326+
MongoClient mongoClient = MongoClients.create("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");
327+
328+
.. note::
329+
330+
The method refers to the ``PLAIN`` authentication mechanism instead of
331+
``LDAP`` because the driver authenticates by using the ``PLAIN``
332+
SASL mechanism.

0 commit comments

Comments
 (0)