Update custom authenticator docs to include identifier normalization

Improve the documentation for custom authenticators by detailing the concept of user identifier normalization. Introduced the `NormalizedUserBadge` example to demonstrate how to simplify and standardize identifiers. Clarified how normalization avoids duplicates and ensures consistent user recognition.

Author: Spomky

security/custom_authenticator.rst

@@ -209,13 +209,20 @@ requires a user and some sort of "credentials" (e.g. a password).
 Use the
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Badge\\UserBadge`
 to attach the user to the passport. The ``UserBadge`` requires a user
-identifier (e.g. the username or email), which is used to load the user
-using :ref:`the user provider <security-user-providers>`::
+identifier (e.g. the username or email)::
 
     use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
 
     // ...
-    $passport = new Passport(new UserBadge($email), $credentials);
+    $passport = new Passport(new UserBadge($userIdentifier), $credentials);
+
+User Identifier
+~~~~~~~~~~~~~~~
+
+The user identifier is a unique string that identifies the user. It is used
+ to load the user using :ref:`the user provider <security-user-providers>`.
+This identifier is often something like the user's email address or username,
+but it could be any unique value associated with the user.
 
 .. note::
 
@@ -255,6 +262,84 @@ using :ref:`the user provider <security-user-providers>`::
             }
         }
 
+It is a good practice to normalize the user identifier before using it.
+For example, this ensures that variations such as "john.doe", "John.Doe",
+or "JOHN.DOE" refer to the same user.
+Normalization can include converting the identifier to lowercase
+and trimming unnecessary spaces.
+You can optionally pass a user identifier normalizer as third argument to the
+``UserBadge``. This callable receives the ``$userIdentifier``
+and must return a normalized user identifier as a string.
+
+    // src/Security/NormalizedUserBadge.php
+    namespace App\Security;
+
+    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
+    use Symfony\Component\String\UnicodeString;
+    use function Symfony\Component\String\u;
+
+    final class NormalizedUserBadge extends UserBadge
+    {
+        public function __construct(string $identifier)
+        {
+            $callback = static fn (string $identifier) => u($identifier)->normalize(UnicodeString::NFKC)->ascii()->lower()->toString();
+
+            parent::__construct($identifier, null, $callback);
+        }
+    }
+
+    // src/Security/PasswordAuthenticator.php
+    namespace App\Security;
+
+    final class PasswordAuthenticator extends AbstractLoginFormAuthenticator
+    {
+        // Simplified for brievety
+        public function authenticate(Request $request): Passport
+        {
+            $username = (string) $request->request->get('username', '');
+            $password = (string) $request->request->get('password', '');
+
+            $request->getSession()
+                ->set(SecurityRequestAttributes::LAST_USERNAME, $username);
+
+            return new Passport(
+                new NormalizedUserBadge($username),
+                new PasswordCredentials($password),
+                [
+                    //All other useful badges
+                ]
+            );
+        }
+    }
+
+.. note::
+
+    Similarly, Google normalizes email addresses so that "john.doe", "j.hon.d.oe",
+    and "johndoe" all correspond to the same account.
+    This involves removing dots and converting the email address to lowercase
+    (though normalization specifics depend on your use case).
+
+.. note::
+
+    In enterprise applications, a user may need to use their identifier in multiple formats,
+    such as:
+    - ``[email protected]``
+    - ``acme.com\jdoe``
+    - ``https://acme.com/+jdoe``
+    - ``acct:[email protected]``
+
+    Normalizing these identifiers (e.g., converting to lowercase, trimming spaces,
+    or unifying formats) simplifies searches and ensures that the same user identity
+    is consistently recognized.
+    This is particularly useful to avoid duplicates caused by format variations.
+
+User Credential
+~~~~~~~~~~~~~~~
+
+The user credential is used to authenticate the user i.e. to verify
+the validity of the provided information (such as a password, an API token,
+or other custom credentials).
+
 The following credential classes are supported by default:
 
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Credentials\\PasswordCredentials`