DOCS-11100: LDAP - substituted DNs must be RFC4514 escaped

Author: schmalliso

source/core/security-ldap-external.txt

@@ -403,10 +403,11 @@ MongoDB maps each returned group distinguished name (DN) returned by
 the LDAP :setting:`query <ldap.security.authz.queryTemplate>` to a
 :ref:`role <authorization>` on the ``admin`` database.
 
-If MongoDB acquires a group whose DN exactly matches the name of an existing
-role, MongoDB grants the authenticated user roles and :ref:`privileges
-<privileges>` associated with that role. If MongoDB cannot map any of the
-returned groups to a role, MongoDB grants no privileges to the user.
+If MongoDB acquires a group whose DN **exactly** matches the name of an
+existing role, MongoDB grants the authenticated user roles and
+:ref:`privileges <privileges>` associated with that role. If MongoDB
+cannot map any of the returned groups to a role, MongoDB grants no
+privileges to the user.
 
 .. note::
 
@@ -417,6 +418,13 @@ returned groups to a role, MongoDB grants no privileges to the user.
    appropriate roles in the ``admin`` database. Users still authenticate
    against the ``$external`` database.
 
+.. important::
+
+   If you are using LDAP for authorization and your LDAP group DNs
+   contain `RFC4514 <https://tools.ietf.org/html/rfc4514>`_ escaped
+   sequences, the roles you create in the ``admin`` database must also
+   be escaped following RFC4514.
+
 .. example::
 
    A database has the following roles configured on the ``admin`` database:

source/includes/admonition-important-userToDNMapping-escape.rst

@@ -0,0 +1,6 @@
+.. important::
+  
+   If you use :setting:`~security.ldap.userToDNMapping`\'s
+   ``substitution`` parameter to transform the group name, the result
+   of the substitution **must** be an `RFC4514
+   <https://www.ietf.org/rfc/rfc4514.txt>`_ escaped string.

source/includes/options-mongod.yaml

@@ -2594,6 +2594,9 @@ description: |
          corresponding `regex capture group
          <http://www.regular-expressions.info/refcapture.html>`_ extracted
          from the authentication username via the ``match`` regex.
+         
+         The result of the substitution must be an `RFC4514
+         <https://www.ietf.org/rfc/rfc4514.txt>`_ escaped string.
 
        - ``"cn={0},ou=engineering,
          dc=example,dc=com"``
@@ -2614,6 +2617,14 @@ description: |
        - ``"ou=engineering,dc=example,
          dc=com??one?(user={0})"``
 
+  .. note::
+
+     An explanation of  `RFC4514 <https://www.ietf.org/rfc/rfc4514.txt>`_,
+     `RFC4515 <https://tools.ietf.org/search/rfc4515>`_,
+     `RFC4516 <https://tools.ietf.org/html/rfc4516>`_, or LDAP queries is out
+     of scope for the MongoDB Documentation. Please review the RFC directly or
+     use your preferred LDAP resource.
+
   For each document in the array, you must use either ``substitution`` or
   ``ldapQuery``. You *cannot* specify both in the same document.
 
@@ -2672,13 +2683,6 @@ description: |
   This setting can be configured on a running {{program}} using the
   :dbcommand:`setParameter` database command.
 
-  .. note::
-
-     An explanation of `RFC4515 <https://tools.ietf.org/search/rfc4515>`_,
-     `RFC4516 <https://tools.ietf.org/html/rfc4516>`_ or LDAP queries is out
-     of scope for the MongoDB Documentation. Please review the RFC directly or
-     use your preferred LDAP resource.
-
 ---
 program: mongod
 name: ldapAuthzQueryTemplate

source/includes/steps-configure-ldap-sasl-activedirectory-authentication.yaml

@@ -217,6 +217,9 @@ pre: |
      :setting:`~security.ldap.authz.queryTemplate`, replacing the ``{USER}``
      token with the *transformed* username
      ``CN=alice,CN=Users,DC=engineering,DC=example,DC=com``.
+
+  .. include:: /includes/admonition-important-userToDNMapping-escape.rst
+
 ---
 title: Configure query credentials.
 stepnum: 8

source/includes/steps-kerberos-auth-activedirectory-authz.yaml

@@ -375,6 +375,8 @@ pre: |
      token with the *transformed* username
      ``CN=alice,CN=Users,DC=engineering,DC=example,DC=com``.
 
+  .. include:: /includes/admonition-important-userToDNMapping-escape.rst
+
 ---
 title: Configure query credentials.
 stepnum: 10