DOCSP-2214: Clarify SASL mechanism support, highlight GSSAPI

source/includes/options-conf.yaml

@@ -1967,6 +1967,7 @@ inherit:
 replacement:
   program: ":binary:`~bin.mongod` or :binary:`~bin.mongos`"
   bindMethod: :setting:`~security.ldap.bind.method`
+  useOSDefaults: :setting:`~security.ldap.bind.useOSDefaults`
 ---
 program: conf
 name: security.ldap.transportSecurity

source/includes/options-mongod.yaml

@@ -2316,18 +2316,63 @@ description: |
 
   A comma-separated list of SASL mechanisms {{program}} can
   use when authenticating to the LDAP server. The {{program}} and the
-  LDAP server must agree on at least one mechanism.
+  LDAP server must agree on at least one mechanism. The {{program}} 
+  dynamically loads any SASL mechanism libraries installed on the host 
+  machine at runtime.
+
+  Install and configure the appropriate libraries for the selected
+  SASL mechanism(s) on both the {{program}} host and the remote
+  LDAP server host. Your operating system may include certain SASL
+  libraries by default. Defer to the documentation associated with each 
+  SASL mechanism for guidance on installation and configuration.
+
+  If using the ``GSSAPI`` SASL mechanism for use with
+  :ref:`security-kerberos`, verify the following for the
+  {{program}} host machine:
+
+  ``Linux``
+    - The ``KRB5_CLIENT_KTNAME`` environment
+      variable resolves to the name of the client :ref:`keytab-files` 
+      for the host machine. For more on Kerberos environment
+      variables, please defer to the
+      `Kerberos documentation <https://web.mit.edu/kerberos/krb5-1.13/doc/admin/env_variables.html>`__. 
+    - The client keytab includes a
+      :ref:`kerberos-user-principal` for the {{program}} to use when
+      connecting to the LDAP server and execute LDAP queries.
+
+  ``Windows``
+    If connecting to an Active Directory server, the Windows
+    Kerberos configuration automatically generates a
+    `Ticket-Granting-Ticket <https://msdn.microsoft.com/en-us/library/windows/desktop/aa380510(v=vs.85).aspx>`__
+    when the user logs onto the system. Set {{useOSDefaults}} to 
+    ``true`` to allow {{program}} to use the generated credentials when 
+    connecting to the Active Directory server and execute queries.
 
   Set {{bindMethod}} to ``sasl`` to use this option.
 
   .. note::
 
-     A complete list of SASL mechanisms is out of scope for this
-     documentation. See the IANA list of `SASL mechanisms
-     <http://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml>`_,
-     as well as the documentation for your LDAP service.
+     For a complete list of SASL mechanisms see the  
+     `IANA listing
+     <http://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml>`_.
+     Defer to the documentation for your LDAP or Active Directory
+     service for identifying the SASL mechanisms compatible with the
+     service. 
+
+     MongoDB is not a source of SASL mechanism libraries, nor 
+     is the MongoDB documentation a definitive source for
+     installing or configuring any given SASL mechanism. For 
+     documentation and support, defer to the SASL mechanism 
+     library vendor or owner.
+
+     For more information on SASL, defer to the following resources:
+
+     - For Linux, please see the `Cyrus SASL documentation <https://www.cyrusimap.org/sasl/>`__.
+     - For Windows, please see the `Windows SASL documentation <https://msdn.microsoft.com/en-us/library/cc223500.aspx>`__.
+
 replacement:
   bindMethod: ":option:`--ldapBindMethod`"
+  useOSDefaults: ":option:`--ldapBindWithOSDefaults`"
 ---
 program: mongod
 name: ldapTransportSecurity