DOCS-9897: authMechanismProperties for URI connection string

source/reference/connection-string.txt

@@ -612,17 +612,59 @@ Authentication Options
        :doc:`/tutorial/configure-x509-client-authentication` for more
        information on x509 authentication.
 
+   * - .. urioption:: authMechanismProperties
+
+     - Specify properties for the specified :urioption:`authMechanism`
+       as a comma-separated list of colon-separated key-value pairs. 
+       For example: 
+
+       .. code-block:: shell
+          :copyable: false
+
+          authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:true
+
+       The :option:`authmechanismProperties` option is only supported 
+       when :urioption:`authMechanism` is 
+       :ref:`GSSAPI <security-auth-kerberos>`. Possible values are:
+
+       ``SERVICE_NAME:<string>``
+         Set the Kerberos service name when connecting to Kerberized
+         MongoDB instances. This value must match the service name set
+         on MongoDB instances to which you are connecting. 
+
+         ``SERVICE_NAME`` defaults to ``mongodb`` for all clients and 
+         MongoDB instances. If you change the
+         :parameter:`saslServiceName` setting on a MongoDB instance, you
+         must set ``SERVICE_NAME`` to match that setting.
+
+       ``CANONICALIZE_HOST_NAME:true|false``
+         Canonicalize the hostname of the client host machine when 
+         connecting to the Kerberos server. This may be required when
+         hosts report different hostnames than what is in the Kerberos
+         database. Defaults to ``false``.
+
+       ``SERVICE_REALM:<string>``
+         Set the Kerberos realm for the MongoDB service. This may be
+         necessary to support cross-realm authentication where the user
+         exists in one realm and the service in another.
+
    * - .. urioption:: gssapiServiceName
 
      - Set the Kerberos service name when connecting to Kerberized
        MongoDB instances. This value must match the service name set on
-       MongoDB instances.
+       MongoDB instances to which you are connecting.
 
        :urioption:`gssapiServiceName` defaults to ``mongodb`` for all
-       clients and for MongoDB instance. If you change
+       clients and MongoDB instances. If you change
        :parameter:`saslServiceName` setting on a MongoDB instance, you
-       will need to set :urioption:`gssapiServiceName` to the same
-       value.
+       must set :urioption:`gssapiServiceName` to match that setting.
+
+       :urioption:`gssapiServiceName` is a deprecated aliases for
+       :urioption:`authMechanismProperties=SERVICE_NAME:mongodb 
+       <authMechanismProperties>`. For more information on which 
+       options your driver supports and their relative priority to each 
+       other, reference the documentation for your preferred driver 
+       version.
 
 .. _selection-discovery-options: