Skip to content

Commit 7836171

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-41818 Add Enterprise Authentication page (#79)
1 parent 50f67a4 commit 7836171

File tree

4 files changed

+554
-111
lines changed

4 files changed

+554
-111
lines changed

‎source/includes/security/enterprise-authentication.java‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// start-gssapi-connection-string
2+
MongoClient mongoClient = MongoClients
3+
.create("<username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI");
4+
// end-gssapi-connection-string
5+
6+
// start-gssapi-mongocredential
7+
MongoCredential credential = MongoCredential.createGSSAPICredential("<username>");
8+
9+
MongoClient mongoClient = MongoClients.create(
10+
MongoClientSettings.builder()
11+
.applyToClusterSettings(builder ->
12+
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
13+
.credential(credential)
14+
.build());
15+
// end-gssapi-mongocredential
16+
17+
// start-gssapi-connection-string-properties
18+
MongoClient mongoClient = MongoClients
19+
.create("<username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService");
20+
// end-gssapi-connection-string-properties
21+
22+
// start-gssapi-service-key
23+
MongoCredential credential = MongoCredential
24+
.createGSSAPICredential("<username>");
25+
credential = credential
26+
.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "<myService>");
27+
// end-gssapi-service-key
28+
29+
// start-gssapi-subject-key
30+
LoginContext loginContext = new LoginContext(<LoginModule implementation from JAAS config>);
31+
loginContext.login();
32+
Subject subject = loginContext.getSubject();
33+
34+
MongoCredential credential = MongoCredential
35+
.createGSSAPICredential("<username>");
36+
credential = credential
37+
.withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject);
38+
// end-gssapi-subject-key
39+
40+
// start-gssapi-ticket-cache
41+
/* All MongoClient instances sharing this instance of KerberosSubjectProvider
42+
will share a Kerberos ticket cache */
43+
String myLoginContext = "myContext";
44+
MongoCredential credential = MongoCredential
45+
.createGSSAPICredential(<username>);
46+
47+
/* Login context defaults to "com.sun.security.jgss.krb5.initiate"
48+
if unspecified in KerberosSubjectProvider */
49+
credential = credential
50+
.withMechanismProperty(MongoCredential.JAVA_SUBJECT_PROVIDER_KEY,
51+
new KerberosSubjectProvider(myLoginContext));
52+
// end-gssapi-ticket-cache
53+
54+
// start-ldap-connection-string
55+
MongoClient mongoClient = MongoClients
56+
.create("<ldap_username>:<ldap_password>@<hostname>:<port>/?authSource=$external&authMechanism=PLAIN");
57+
// end-ldap-connection-string
58+
59+
// start-ldap-mongocredential
60+
MongoCredential credential = MongoCredential
61+
.createPlainCredential(<ldap_username>, "$external", <ldap_password>);
62+
63+
MongoClient mongoClient = MongoClients.create(
64+
MongoClientSettings.builder()
65+
.applyToClusterSettings(builder ->
66+
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
67+
.credential(credential)
68+
.build());
69+
// end-ldap-mongocredential
70+
71+
// start-azure-oidc-connection-string
72+
MongoClient mongoClient = MongoClients.create(
73+
"mongodb://<username>@<hostname>:<port>/?" +
74+
"?authMechanism=MONGODB-OIDC" +
75+
"&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");
76+
// end-azure-oidc-connection-string
77+
78+
// start-azure-oidc-mongocredential
79+
MongoCredential credential = MongoCredential.createOidcCredential("<username>")
80+
.withMechanismProperty("ENVIRONMENT", "azure")
81+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>");
82+
83+
MongoClient mongoClient = MongoClients.create(
84+
MongoClientSettings.builder()
85+
.applyToClusterSettings(builder ->
86+
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
87+
.credential(credential)
88+
.build());
89+
// end-azure-oidc-mongocredential
90+
91+
// start-gcp-oidc-connection-string
92+
MongoClient mongoClient = MongoClients.create(
93+
"mongodb://<hostname>:<port>/?" +
94+
"authMechanism=MONGODB-OIDC" +
95+
"&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>");
96+
// end-gcp-oidc-connection-string
97+
98+
// start-gcp-oidc-mongocredential
99+
MongoCredential credential = MongoCredential.createOidcCredential()
100+
.withMechanismProperty("ENVIRONMENT", "gcp")
101+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>");
102+
103+
MongoClient mongoClient = MongoClients.create(
104+
MongoClientSettings.builder()
105+
.applyToClusterSettings(builder ->
106+
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
107+
.credential(credential)
108+
.build());
109+
// end-gcp-oidc-mongocredential
110+
111+
// start-oidc-callback-create
112+
MongoCredential credential = MongoCredential.createOidcCredential(null)
113+
.withMechanismProperty("OIDC_CALLBACK", (context) -> {
114+
String accessToken = ...
115+
return new OidcCallbackResult(accessToken);
116+
});
117+
// end-oidc-callback-create
118+
119+
// start-oidc-callback
120+
MongoCredential credential = MongoCredential.createOidcCredential(null)
121+
.withMechanismProperty("OIDC_CALLBACK", (context) -> {
122+
string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat"));
123+
return new OidcCallbackResult(accessToken);
124+
});
125+
126+
MongoClient mongoClient = MongoClients.create(
127+
MongoClientSettings.builder()
128+
.applyToClusterSettings(builder ->
129+
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
130+
.credential(credential)
131+
.build());
132+
// end-oidc-callback

‎source/secure-your-data.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Secure Your Data
2323
:maxdepth: 1
2424

2525
/security/auth
26+
/security/enterprise-authentication
2627
/security/encrypt
2728

2829
Overview

‎source/security/auth.txt‎

Lines changed: 4 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,10 @@ Authentication
1717
:depth: 2
1818
:class: singlecol
1919

20-
The driver supports all MongoDB authentication mechanisms,
21-
including those available only in the MongoDB Enterprise Edition.
20+
In this guide, you can learn how to authenticate with MongoDB using the
21+
authentication mechanisms available in the MongoDB Community Edition.
22+
Authentication mechanisms are processes by which the driver and server confirm
23+
the identity of a client to ensure security before connecting.
2224

2325
MongoCredential
2426
---------------
@@ -228,112 +230,3 @@ Or, you can use a connection string that explicitly specifies
228230
See the :manual:`Use x.509 Certificates to Authenticate Clients </tutorial/configure-x509-client-authentication/>`
229231
tutorial in the Server manual to learn more about
230232
determining the subject name from the certificate.
231-
232-
Kerberos (GSSAPI)
233-
-----------------
234-
235-
MongoDB Enterprise supports proxy authentication through the Kerberos
236-
service. To create a credential of type Kerberos (GSSAPI), use the
237-
``createGSSAPICredential()`` static factory method:
238-
239-
.. code-block:: java
240-
241-
String user; // The Kerberos user name, including the realm, e.g. "[email protected]"
242-
// ...
243-
MongoCredential credential = MongoCredential.createGSSAPICredential(user);
244-
245-
MongoClient mongoClient = MongoClients.create(
246-
MongoClientSettings.builder()
247-
.applyToClusterSettings(builder ->
248-
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
249-
.credential(credential)
250-
.build());
251-
252-
Or, you can use a connection string that explicitly specifies
253-
``authMechanism=GSSAPI``:
254-
255-
.. code-block:: java
256-
257-
MongoClient mongoClient = MongoClients.create("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI");
258-
259-
.. note::
260-
261-
The method refers to the ``GSSAPI`` authentication mechanism instead of
262-
``Kerberos`` because the driver authenticates by using the ``GSSAPI`` SASL mechanism.
263-
264-
To successfully authenticate by using Kerberos, the application typically
265-
must specify several system properties so that the underlying GSSAPI
266-
Java libraries can acquire a Kerberos ticket:
267-
268-
.. code-block:: none
269-
270-
java.security.krb5.realm=MYREALM.ME
271-
java.security.krb5.kdc=mykdc.myrealm.me
272-
273-
Depending on the Kerberos setup, additional property specifications
274-
might be required, either within the application code or, in some cases,
275-
by using the ``withMechanismProperty()`` method of the ``MongoCredential``
276-
instance:
277-
278-
- ``SERVICE_NAME``
279-
- ``CANONICALIZE_HOST_NAME``
280-
- ``JAVA_SUBJECT``
281-
- ``JAVA_SASL_CLIENT_PROPERTIES``
282-
283-
The following code shows how to specify the ``SERVICE_NAME`` property within the
284-
``MongoCredential`` object:
285-
286-
.. code-block:: java
287-
288-
credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "othername");
289-
290-
Or, you can specify the ``SERVICE_NAME`` property within the ``ConnectionString``:
291-
292-
.. code-block:: java
293-
294-
uri = "mongodb://username%40MYREALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername"
295-
296-
.. note::
297-
298-
On Windows, Oracles JRE uses `LSA
299-
<https://msdn.microsoft.com/en-us/library/windows/desktop/aa378326.aspx>`__
300-
rather than `SSPI
301-
<https://msdn.microsoft.com/en-us/library/windows/desktop/aa380493.aspx>`__
302-
in its implementation of GSSAPI, which limits interoperability with Windows
303-
Active Directory and in particular the ability to implement single
304-
sign-on.
305-
306-
LDAP (PLAIN)
307-
------------
308-
309-
MongoDB Enterprise supports proxy authentication through a
310-
Lightweight Directory Access Protocol (LDAP) service. To create a
311-
credential of type ``LDAP`` use the ``createPlainCredential()`` static
312-
factory method:
313-
314-
.. code-block:: java
315-
316-
String user; // The LDAP user name
317-
char[] password; // The LDAP password
318-
// ...
319-
MongoCredential credential = MongoCredential.createPlainCredential(user, "$external", password);
320-
321-
MongoClient mongoClient = MongoClients.create(
322-
MongoClientSettings.builder()
323-
.applyToClusterSettings(builder ->
324-
builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
325-
.credential(credential)
326-
.build());
327-
328-
Or, you can use a connection string that explicitly specifies
329-
``authMechanism=PLAIN``:
330-
331-
.. code-block:: java
332-
333-
MongoClient mongoClient = MongoClients.create("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");
334-
335-
.. note::
336-
337-
The method refers to the ``PLAIN`` authentication mechanism instead of
338-
``LDAP`` because the driver authenticates by using the ``PLAIN``
339-
SASL mechanism.

0 commit comments

Comments
 (0)