[Security] Deprecate {username} in favor of {user_identifier}

Author: javiereguiluz

reference/configuration/security.rst

@@ -610,9 +610,9 @@ This is the name of your configured LDAP client.
 dn_string
 .........
 
-**type**: ``string`` **default**: ``{username}``
+**type**: ``string`` **default**: ``{user_identifier}``
 
-This is the string which will be used as the bind DN. The ``{username}``
+This is the string which will be used as the bind DN. The ``{user_identifier}``
 placeholder will be replaced with the user-provided value (their login).
 Depending on your LDAP server's configuration, you may need to override
 this value.
@@ -622,7 +622,7 @@ query_string
 
 **type**: ``string`` **default**: ``null``
 
-This is the string which will be used to query for the DN. The ``{username}``
+This is the string which will be used to query for the DN. The ``{user_identifier}``
 placeholder will be replaced with the user-provided value (their login).
 Depending on your LDAP server's configuration, you will need to override
 this value. This setting is only necessary if the user's DN cannot be derived

security/ldap.rst

@@ -290,14 +290,19 @@ filter
 
 This key lets you configure which LDAP query will be used. The ``{uid_key}``
 string will be replaced by the value of the ``uid_key`` configuration value
-(by default, ``sAMAccountName``), and the ``{username}`` string will be
-replaced by the username you are trying to load.
+(by default, ``sAMAccountName``), and the ``{user_identifier}`` string will be
+replaced by the user identified you are trying to load.
+
+.. deprecated:: 6.2
+
+    Starting from Symfony 6.2, the ``{username}`` string was deprecated in favor
+    of ``{user_identifier}``.
 
 For example, with a ``uid_key`` of ``uid``, and if you are trying to
 load the user ``fabpot``, the final string will be: ``(uid=fabpot)``.
 
 If you pass ``null`` as the value of this option, the default filter is used
-``({uid_key}={username})``.
+``({uid_key}={user_identifier})``.
 
 To prevent `LDAP injection`_, the username will be escaped.
 
@@ -324,15 +329,15 @@ number or contain white spaces.
 dn_string
 .........
 
-**type**: ``string`` **default**: ``{username}``
+**type**: ``string`` **default**: ``{user_identifier}``
 
 This key defines the form of the string used to compose the
-DN of the user, from the username. The ``{username}`` string is
+DN of the user, from the username. The ``{user_identifier}`` string is
 replaced by the actual username of the person trying to authenticate.
 
 For example, if your users have DN strings in the form
 ``uid=einstein,dc=example,dc=com``, then the ``dn_string`` will be
-``uid={username},dc=example,dc=com``.
+``uid={user_identifier},dc=example,dc=com``.
 
 query_string
 ............
@@ -342,8 +347,8 @@ query_string
 This (optional) key makes the user provider search for a user and then use the
 found DN for the bind process. This is useful when using multiple LDAP user
 providers with different ``base_dn``. The value of this option must be a valid
-search string (e.g. ``uid="{username}"``). The placeholder value will be
-replaced by the actual username.
+search string (e.g. ``uid="{user_identifier}"``). The placeholder value will be
+replaced by the actual user identifier.
 
 When this option is used, ``query_string`` will search in the DN specified by
 ``dn_string`` and the DN resulted of the ``query_string`` will be used to
@@ -376,7 +381,7 @@ Configuration example for form login
                     form_login_ldap:
                         # ...
                         service: Symfony\Component\Ldap\Ldap
-                        dn_string: 'uid={username},dc=example,dc=com'
+                        dn_string: 'uid={user_identifier},dc=example,dc=com'
 
     .. code-block:: xml
 
@@ -393,7 +398,7 @@ Configuration example for form login
             <config>
                 <firewall name="main">
                     <form-login-ldap service="Symfony\Component\Ldap\Ldap"
-                        dn-string="uid={username},dc=example,dc=com"/>
+                        dn-string="uid={user_identifier},dc=example,dc=com"/>
                 </firewall>
             </config>
         </srv:container>
@@ -408,7 +413,7 @@ Configuration example for form login
             $security->firewall('main')
                 ->formLoginLdap()
                     ->service(Ldap::class)
-                    ->dnString('uid={username},dc=example,dc=com')
+                    ->dnString('uid={user_identifier},dc=example,dc=com')
             ;
         };
 
@@ -428,7 +433,7 @@ Configuration example for HTTP Basic
                     stateless: true
                     http_basic_ldap:
                         service: Symfony\Component\Ldap\Ldap
-                        dn_string: 'uid={username},dc=example,dc=com'
+                        dn_string: 'uid={user_identifier},dc=example,dc=com'
 
     .. code-block:: xml
 
@@ -447,7 +452,7 @@ Configuration example for HTTP Basic
 
                 <firewall name="main" stateless="true">
                     <http-basic-ldap service="Symfony\Component\Ldap\Ldap"
-                        dn-string="uid={username},dc=example,dc=com"/>
+                        dn-string="uid={user_identifier},dc=example,dc=com"/>
                 </firewall>
             </config>
         </srv:container>
@@ -463,7 +468,7 @@ Configuration example for HTTP Basic
                 ->stateless(true)
                 ->formLoginLdap()
                     ->service(Ldap::class)
-                    ->dnString('uid={username},dc=example,dc=com')
+                    ->dnString('uid={user_identifier},dc=example,dc=com')
             ;
         };
 
@@ -484,7 +489,7 @@ Configuration example for form login and query_string
                     form_login_ldap:
                         service: Symfony\Component\Ldap\Ldap
                         dn_string: 'dc=example,dc=com'
-                        query_string: '(&(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))'
+                        query_string: '(&(uid={user_identifier})(memberOf=cn=users,ou=Services,dc=example,dc=com))'
                         search_dn: '...'
                         search_password: 'the-raw-password'
 
@@ -505,7 +510,7 @@ Configuration example for form login and query_string
                     <!-- ... -->
                     <form-login-ldap service="Symfony\Component\Ldap\Ldap"
                         dn-string="dc=example,dc=com"
-                        query-string="(&amp;(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))"
+                        query-string="(&amp;(uid={user_identifier})(memberOf=cn=users,ou=Services,dc=example,dc=com))"
                         search-dn="..."
                         search-password="the-raw-password"/>
                 </firewall>
@@ -524,7 +529,7 @@ Configuration example for form login and query_string
                 ->formLoginLdap()
                     ->service(Ldap::class)
                     ->dnString('dc=example,dc=com')
-                    ->queryString('(&(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))')
+                    ->queryString('(&(uid={user_identifier})(memberOf=cn=users,ou=Services,dc=example,dc=com))')
                     ->searchDn('...')
                     ->searchPassword('the-raw-password')
             ;