DOCSP-41818 Add Enterprise Authentication page

source/includes/security/enterprise-authentication.java

@@ -0,0 +1,132 @@
+// start-gssapi-connection-string
+MongoClient mongoClient = MongoClients
+    .create("<username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI");
+// end-gssapi-connection-string
+
+// start-gssapi-mongocredential
+MongoCredential credential = MongoCredential.createGSSAPICredential("<username>");
+
+MongoClient mongoClient = MongoClients.create(
+    MongoClientSettings.builder()
+        .applyToClusterSettings(builder ->
+                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+        .credential(credential)
+        .build());
+// end-gssapi-mongocredential
+
+// start-gssapi-connection-string-properties
+MongoClient mongoClient = MongoClients
+    .create("<username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService");
+// end-gssapi-connection-string-properties
+
+// start-gssapi-service-key
+MongoCredential credential = MongoCredential
+    .createGSSAPICredential("<username>");
+credential = credential
+    .withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "<myService>");
+// end-gssapi-service-key
+
+// start-gssapi-subject-key
+LoginContext loginContext = new LoginContext(<LoginModule implementation from JAAS config>);
+loginContext.login();
+Subject subject = loginContext.getSubject();
+
+MongoCredential credential = MongoCredential
+    .createGSSAPICredential("<username>");
+credential = credential
+    .withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject);
+// end-gssapi-subject-key
+
+// start-gssapi-ticket-cache
+/* All MongoClient instances sharing this instance of KerberosSubjectProvider
+will share a Kerberos ticket cache */
+String myLoginContext = "myContext";
+MongoCredential credential = MongoCredential
+    .createGSSAPICredential(<username>);
+
+/* Login context defaults to "com.sun.security.jgss.krb5.initiate"
+if unspecified in KerberosSubjectProvider */
+credential = credential
+    .withMechanismProperty(MongoCredential.JAVA_SUBJECT_PROVIDER_KEY, 
+        new KerberosSubjectProvider(myLoginContext));
+// end-gssapi-ticket-cache
+
+// start-ldap-connection-string
+MongoClient mongoClient = MongoClients
+    .create("<ldap_username>:<ldap_password>@<hostname>:<port>/?authSource=$external&authMechanism=PLAIN");
+// end-ldap-connection-string
+
+// start-ldap-mongocredential
+MongoCredential credential = MongoCredential
+    .createPlainCredential(<ldap_username>, "$external", <ldap_password>);
+
+MongoClient mongoClient = MongoClients.create(
+    MongoClientSettings.builder()
+        .applyToClusterSettings(builder ->
+                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+        .credential(credential)
+        .build());
+// end-ldap-mongocredential
+
+// start-azure-oidc-connection-string
+MongoClient mongoClient = MongoClients.create(
+            "mongodb://<username>@<hostname>:<port>/?" + 
+            "?authMechanism=MONGODB-OIDC" +
+            "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");
+// end-azure-oidc-connection-string
+
+// start-azure-oidc-mongocredential
+MongoCredential credential = MongoCredential.createOidcCredential("<username>")
+.withMechanismProperty("ENVIRONMENT", "azure")  
+.withMechanismProperty("TOKEN_RESOURCE", "<audience>");
+
+MongoClient mongoClient = MongoClients.create(
+ MongoClientSettings.builder()
+     .applyToClusterSettings(builder ->
+             builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+     .credential(credential)
+     .build());
+// end-azure-oidc-mongocredential
+
+// start-gcp-oidc-connection-string
+MongoClient mongoClient = MongoClients.create(
+    "mongodb://<hostname>:<port>/?" +
+    "authMechanism=MONGODB-OIDC" +
+    "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>");
+// end-gcp-oidc-connection-string
+
+// start-gcp-oidc-mongocredential
+MongoCredential credential = MongoCredential.createOidcCredential()
+            .withMechanismProperty("ENVIRONMENT", "gcp")
+            .withMechanismProperty("TOKEN_RESOURCE", "<audience>");
+
+MongoClient mongoClient = MongoClients.create(
+    MongoClientSettings.builder()
+        .applyToClusterSettings(builder ->
+                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+        .credential(credential)
+        .build());
+// end-gcp-oidc-mongocredential
+
+// start-oidc-callback-create
+MongoCredential credential = MongoCredential.createOidcCredential(null)
+    .withMechanismProperty("OIDC_CALLBACK", (context) ->  {
+       String accessToken = ...
+       return new OidcCallbackResult(accessToken);
+});
+// end-oidc-callback-create
+
+// start-oidc-callback
+MongoCredential credential = MongoCredential.createOidcCredential(null)
+      .withMechanismProperty("OIDC_CALLBACK", (context) ->  {
+         string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat"));
+         return new OidcCallbackResult(accessToken);
+      });
+
+   MongoClient mongoClient = MongoClients.create(
+       MongoClientSettings.builder()
+           .applyToClusterSettings(builder ->
+                   builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+           .credential(credential)
+           .build());
+// end-oidc-callback

source/secure-your-data.txt

@@ -23,6 +23,7 @@ Secure Your Data
     :maxdepth: 1
 
     /security/auth
+    /security/enterprise-authentication
     /security/encrypt
 
 Overview

source/security/auth.txt

@@ -17,8 +17,10 @@ Authentication
    :depth: 2
    :class: singlecol
 
-The driver supports all MongoDB authentication mechanisms,
-including those available only in the MongoDB Enterprise Edition.
+In this guide, you can learn how to authenticate with MongoDB using the
+authentication mechanisms available in the MongoDB Community Edition.
+Authentication mechanisms are processes by which the driver and server confirm
+the identity of a client to ensure security before connecting.
 
 MongoCredential
 ---------------
@@ -228,112 +230,3 @@ Or, you can use a connection string that explicitly specifies
 See the :manual:`Use x.509 Certificates to Authenticate Clients </tutorial/configure-x509-client-authentication/>`
 tutorial in the Server manual to learn more about
 determining the subject name from the certificate.
-
-Kerberos (GSSAPI)
------------------
-
-MongoDB Enterprise supports proxy authentication through the Kerberos
-service. To create a credential of type Kerberos (GSSAPI), use the
-``createGSSAPICredential()`` static factory method:
-
-.. code-block:: java
-
-   String user;   // The Kerberos user name, including the realm, e.g. "user1@MYREALM.ME"
-   // ...
-   MongoCredential credential = MongoCredential.createGSSAPICredential(user);
-
-   MongoClient mongoClient = MongoClients.create(
-       MongoClientSettings.builder()
-           .applyToClusterSettings(builder ->
-               builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
-           .credential(credential)
-           .build());
-
-Or, you can use a connection string that explicitly specifies
-``authMechanism=GSSAPI``:
-
-.. code-block:: java
-
-   MongoClient mongoClient = MongoClients.create("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI");
-
-.. note::
-
-   The method refers to the ``GSSAPI`` authentication mechanism instead of
-   ``Kerberos`` because the driver authenticates by using the ``GSSAPI`` SASL mechanism.
-
-To successfully authenticate by using Kerberos, the application typically
-must specify several system properties so that the underlying GSSAPI
-Java libraries can acquire a Kerberos ticket:
-
-.. code-block:: none
-
-   java.security.krb5.realm=MYREALM.ME
-   java.security.krb5.kdc=mykdc.myrealm.me
-
-Depending on the Kerberos setup, additional property specifications
-might be required, either within the application code or, in some cases,
-by using the ``withMechanismProperty()`` method of the ``MongoCredential``
-instance:
-
-- ``SERVICE_NAME``
-- ``CANONICALIZE_HOST_NAME``
-- ``JAVA_SUBJECT``
-- ``JAVA_SASL_CLIENT_PROPERTIES``
-
-The following code shows how to specify the ``SERVICE_NAME`` property within the
-``MongoCredential`` object:
-
-.. code-block:: java
-
-   credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "othername");
-
-Or, you can specify the ``SERVICE_NAME`` property within the ``ConnectionString``:
-
-.. code-block:: java
-
-   uri = "mongodb://username%40MYREALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername"
-
-.. note::
-
-   On Windows, Oracles JRE uses `LSA
-   <https://msdn.microsoft.com/en-us/library/windows/desktop/aa378326.aspx>`__
-   rather than `SSPI
-   <https://msdn.microsoft.com/en-us/library/windows/desktop/aa380493.aspx>`__
-   in its implementation of GSSAPI, which limits interoperability with Windows
-   Active Directory and in particular the ability to implement single
-   sign-on.
-
-LDAP (PLAIN)
-------------
-
-MongoDB Enterprise supports proxy authentication through a
-Lightweight Directory Access Protocol (LDAP) service. To create a
-credential of type ``LDAP`` use the ``createPlainCredential()`` static
-factory method:
-
-.. code-block:: java
-
-   String user;          // The LDAP user name
-   char[] password;      // The LDAP password
-   // ...
-   MongoCredential credential = MongoCredential.createPlainCredential(user, "$external", password);
-
-   MongoClient mongoClient = MongoClients.create(
-       MongoClientSettings.builder()
-           .applyToClusterSettings(builder ->
-               builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
-           .credential(credential)
-           .build());
-
-Or, you can use a connection string that explicitly specifies
-``authMechanism=PLAIN``:
-
-.. code-block:: java
-
-   MongoClient mongoClient = MongoClients.create("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");
-
-.. note::
-
-   The method refers to the ``PLAIN`` authentication mechanism instead of
-   ``LDAP`` because the driver authenticates by using the ``PLAIN``
-   SASL mechanism.