DOCSP-13803 Kerberos ticket caching (#56)

DOCSP-13803 Kerberos ticket caching

Author: biniona-mongodb

source/fundamentals/enterprise-auth.txt

@@ -93,9 +93,10 @@ mechanism:
       .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi.rst
 
 
-In order to acquire a Kerberos ticket, the GSSAPI Java libraries require
-you to specify the realm and Key Distribution Center (KDC) system
-properties. See the sample settings in the example below:
+In order to acquire a 
+`Kerberos ticket <https://docs.oracle.com/en/java/javase/11/docs/api/java.security.jgss/javax/security/auth/kerberos/KerberosTicket.html>`__,
+the GSSAPI Java libraries require you to specify the realm and Key Distribution 
+Center (KDC) system properties. See the sample settings in the example below:
 
 .. code-block:: none
 
@@ -109,6 +110,7 @@ You may need to specify one or more of the following additional
 - ``CANONICALIZE_HOST_NAME``
 - ``JAVA_SUBJECT``
 - ``JAVA_SASL_CLIENT_PROPERTIES``
+- ``JAVA_SUBJECT_PROVIDER``
 
 .. tabs::
    :hidden:
@@ -123,6 +125,7 @@ You may need to specify one or more of the following additional
 
          - ``JAVA_SUBJECT``
          - ``JAVA_SASL_CLIENT_PROPERTIES``
+         - ``JAVA_SUBJECT_PROVIDER``
 
          Select the :guilabel:`MongoCredential` tab to see how to specify
          them.
@@ -150,12 +153,42 @@ You may need to specify one or more of the following additional
       - :java-docs:`CANONICALIZE_HOST_NAME_KEY </apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#CANONICALIZE_HOST_NAME_KEY>`
       - :java-docs:`JAVA_SUBJECT_KEY </apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SUBJECT_KEY>`
       - :java-docs:`JAVA_SASL_CLIENT_PROPERTIES_KEY </apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SASL_CLIENT_PROPERTIES_KEY>`
+      - :java-docs:`JAVA_SUBJECT_PROVIDER_KEY </apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SUBJECT_PROVIDER_KEY>`
 
       Your code to instantiate a ``MongoClient`` using GSSAPI and additional
       properties might resemble the following:
 
       .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst
 
+
+By default, the Java driver caches Kerberos tickets by ``MongoClient`` instance.
+If your deployment needs to frequently create and destroy ``MongoClient`` instances, 
+you can change the default Kerberos ticket caching behavior to cache by process
+to improve performance.
+
+.. tabs::
+   :hidden:
+
+   .. tab::
+      :tabid: Connection String
+
+      To cache Kerberos tickets by process, you must use the ``MongoCredential`` authentication
+      mechanism, as the connection string authentication mechanism does not support the ``JAVA_SUBJECT_PROVIDER``
+      mechanism property. If you would like to cache Kerberos tickets by process, select the :guilabel:`MongoCredential`
+      tab to learn how to accomplish this.
+
+   .. tab::
+      :tabid: MongoCredential
+
+      To cache Kerberos tickets by process, you must specify the ``JAVA_SUBJECT_PROVIDER``
+      mechanism property and provide a 
+      `KerberosSubjectProvider <https://mongodb.github.io/mongo-java-driver/4.2//apidocs/mongodb-driver-core/com/mongodb/KerberosSubjectProvider.html#%3Cinit%3E()>`__
+      in your ``MongoCredential`` instance. The code to configure the Java driver to cache Kerberos tickets
+      by process should resemble the following:
+
+      .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst
+
+
 .. note::
 
    On Windows, Oracle’s JRE uses `LSA <https://msdn.microsoft.com/en-us/library/windows/desktop/aa378326.aspx>`__

source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst

@@ -0,0 +1,10 @@
+.. code-block:: java
+
+   /* 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));