From 405a74060b82e5b9293c8908ca2916bde7973965 Mon Sep 17 00:00:00 2001
From: Florent Morselli <florent.morselli@spomky-labs.com>
Date: Sun, 18 Dec 2022 11:17:58 +0100
Subject: [PATCH] ``user_identifier`` parameter documentation

---
 reference/configuration/security.rst | 16 +++++++++++++++-
 security.rst                         |  8 ++++----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst
index 4d0f1549ede..ba0eba9a5f2 100644
--- a/reference/configuration/security.rst
+++ b/reference/configuration/security.rst
@@ -666,6 +666,7 @@ X.509 Authentication
                         provider:    your_user_provider
                         user:        SSL_CLIENT_S_DN_Email
                         credentials: SSL_CLIENT_S_DN
+                        user_identifier: emailAddress
 
     .. code-block:: xml
 
@@ -687,6 +688,7 @@ X.509 Authentication
                     <x509 provider="your_user_provider"
                         user="SSL_CLIENT_S_DN_Email"
                         credentials="SSL_CLIENT_S_DN"
+                        user_identifier="emailAddress"
                     />
                 </firewall>
             </config>
@@ -703,6 +705,7 @@ X.509 Authentication
                 ->provider('your_user_provider')
                 ->user('SSL_CLIENT_S_DN_Email')
                 ->credentials('SSL_CLIENT_S_DN')
+                ->user_identifier('emailAddress')
             ;
         };
 
@@ -723,7 +726,18 @@ If the ``user`` parameter is not available, the name of the ``$_SERVER``
 parameter containing the full "distinguished name" of the certificate
 (exposed by e.g. Nginx).
 
-Symfony identifies the value following ``emailAddress=`` in this parameter.
+By default, Symfony identifies the value following ``emailAddress=`` in this parameter.
+This can be changed using the ``user_identifier`` parameter.
+
+user_identifier
+...........
+
+**type**: ``string`` **default**: ``emailAddress``
+
+The ``user_identifier`` parameter is used to find the user identifier in the
+"distinguished name" e.g. ``Subject: C=FR, O=My Organization, CN=user1, emailAddress=user1@myorg.fr``.
+
+By setting this parameter to ``CN``, the returned user identifier will be the "Common Name" ``user1``
 
 .. _reference-security-firewall-remote-user:
 
diff --git a/security.rst b/security.rst
index d8fb76b7db2..70219bd4246 100644
--- a/security.rst
+++ b/security.rst
@@ -1314,11 +1314,11 @@ ways:
 #. First, it tries the ``SSL_CLIENT_S_DN_Email`` server parameter, which is
    exposed by Apache;
 #. If it is not set (e.g. when using Nginx), it uses ``SSL_CLIENT_S_DN`` and
-   matches the value following ``emailAddress=``.
+   matches the value following ``emailAddress``.
 
-You can customize the name of both parameters under the ``x509`` key. See
-:ref:`the configuration reference <reference-security-firewall-x509>` for
-more details.
+You can customize the name of the three parameters under the ``x509`` key.
+See :ref:`the configuration reference <reference-security-firewall-x509>`
+for more details.
 
 Remote Users
 ~~~~~~~~~~~~