DOCS-15864 documentation for enforceUserClusterSeparation parameter (#6789)

* DOCS-15864 documentation for enforceUserClusterSeparation parameter

* DOCS-15864 updates for SJ's feedback

* DOCS-15864 updates for SJ's feedback

* DOCSP-15864 updates for more feedback

* DOCS-15864 updates for JA's feedback

* DOCS-15864 adding enforceUserClusterSeparation to Server Parameters page

* Update source/reference/parameters.txt

Co-authored-by: Jeff Allen <jeffrey.allen@10gen.com>

* DOCS-15864 updates for JA's feedback

---------

Co-authored-by: Jeff Allen <jeffrey.allen@10gen.com>

Author: kanchana-mongodb

source/includes/extracts-x509-certificate.yaml

@@ -29,6 +29,13 @@ content: |
      - Organizational Unit (``OU``)
      - Domain Component (``DC``)
 
+     .. note:: 
+
+        You can also disable the ``enforceUserClusterSeparation``
+        parameter during startup to automatically disable the
+        ``O/OU/DC`` check. This allows member certificates to
+        authenticate as users stored in the ``$external`` database. 
+
    - The ``subject`` of a client x.509 certificate, which contains the 
      Distinguished Name (``DN``), must be **different** than the ``subject``\s 
      of :ref:`member x.509 certificates <x509-member-certificate>`.
@@ -64,6 +71,27 @@ content: |
 
    .. include:: /includes/list-cluster-x509-requirements.rst
 
+   .. note:: 
+
+      If you disable the ``enforceUserClusterSeparation`` parameter, the
+      following behaviors apply: 
+   
+      - The ``O/OU/DC`` check is disabled if ``clusterAuthMode`` is
+        ``keyFile`` in your configuration file. This allows clients
+        possessing member certificates to authenticate as users stored in
+        the ``$external`` database. 
+      - The server won't start if ``clusterAuthMode`` isn't ``keyFile`` in
+        your configuration file. 
+
+      .. include:: /includes/fact-enforce-user-cluster-separation-parameter.rst
+   
+      To set the ``enforceUserClusterSeparation`` parameter to
+      ``false``, run the following command during startup: 
+
+      .. code-block:: javascript
+
+         mongod --setParameter enforceUserClusterSeparation=false
+
    The certificates have the following requirements:
    
    .. include:: /includes/list-tls-certificate-requirements.rst

source/includes/fact-enforce-user-cluster-separation-parameter.rst

@@ -0,0 +1,18 @@
+If you set the ``enforceUserClusterSeparation`` parameter to ``false``,
+the server doesn't distinguish between client certificates, which
+applications use to authenticate, and intra-cluster certificates, which
+have privileged access. This has no effect if your ``clusterAuthMode``
+is ``keyFile``. However, if your ``clusterAuthMode`` is ``x509``, user
+certificates that use the allowed scheme are conflated with cluster
+certificates and granted privileged access. 
+   
+Your existing certificates are granted internal privileges if you do the
+following:  
+      
+1. Create a user, with a name allowed by this parameter.
+#. Set the ``enforceUserClusterSeparation`` parameter to ``false``.
+#. Set ``clusterAuthMode`` to ``x509``.
+   
+You must not upgrade from ``keyFile`` to ``x509`` without validating
+that you've removed users with elevated privileges that the
+``enforceUserClusterSeparation`` flag allowed you to create. 

source/includes/list-cluster-x509-requirements.rst

@@ -19,4 +19,3 @@
         tls:
           clusterAuthX509:
             attributes: O=MongoDB, OU=MongoDB Server
-

source/reference/parameters.txt

@@ -139,13 +139,34 @@ Authentication Parameters
 
    |both|
 
+   *Default*: ``true``
+
    Specify ``0`` or ``false`` to disable localhost authentication
    bypass. Enabled by default.
 
    .. include:: /includes/fact-startup-parameter
 
    See :ref:`localhost-exception` for more information.
 
+.. parameter:: enforceUserClusterSeparation
+
+   |both|
+
+   Set to ``false`` to disable the ``O/OU/DC`` check when
+   ``clusterAuthMode`` is ``keyFile`` in your configuration file. This
+   allows clients possessing member certificates to authenticate as
+   users stored in the ``$external`` database. The server won't start if
+   ``clusterAuthMode`` isn't ``keyFile`` in your configuration file.
+
+   To set the ``enforceUserClusterSeparation`` parameter to ``false``,
+   run the following command during startup: 
+
+   .. code-block:: javascript 
+
+      mongod --setParameter enforceUserClusterSeparation=false
+
+   .. include:: /includes/fact-enforce-user-cluster-separation-parameter.rst
+
 .. parameter:: KeysRotationIntervalSec
 
    *Default*: 7776000 seconds (90 days)