[#14672] Updated more docs related to the UserBadge

Author: wouterj

security/experimental_authenticators.rst

@@ -435,23 +435,61 @@ into a security
 Security Passports
 ~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 5.2
+
+    The ``UserBadge`` was introduced in Symfony 5.2. Prior to 5.2, the user
+    instance was provided directly to the passport.
+
 A passport is an object that contains the user that will be authenticated as
 well as other pieces of information, like whether a password should be checked
 or if "remember me" functionality should be enabled.
 
 The default
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Passport`
-requires a user object and credentials. The following credential classes
-are supported by default:
+requires a user and credentials.
+
+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>`::
+
+    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
+
+    // ...
+    $passport = new Passport(new UserBadge($email), $credentials);
+
+.. note::
 
+    You can optionally pass a user loader as second argument to the
+    ``UserBadge``. This callable receives the ``$userIdentifier``
+    and must return a ``UserInterface`` object (otherwise a
+    ``UsernameNotFoundException`` is thrown)::
+
+        // ...
+        $passport = new Passport(
+            new UserBadge($email, function ($userIdentifier) {
+                return $this->userRepository->findOneBy(['email' => $userIdentifier]);
+            }),
+            $credentials
+        );
+
+The following credential classes are supported by default:
 
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Credentials\\PasswordCredentials`
     This requires a plaintext ``$password``, which is validated using the
-    :ref:`password encoder configured for the user <security-encoding-user-password>`.
+    :ref:`password encoder configured for the user <security-encoding-user-password>`::
+
+        use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\PasswordCredentials;
+
+        // ...
+        return new Passport($user, new PasswordCredentials($plaintextPassword));
 
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Credentials\\CustomCredentials`
     Allows a custom closure to check credentials::
 
+        use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\CustomCredentials;
+
         // ...
         return new Passport($user, new CustomCredentials(
             // If this function returns anything else than `true`, the credentials
@@ -467,21 +505,13 @@ are supported by default:
 
 
 Self Validating Passport
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you don't need any credentials to be checked (e.g. a JWT token), you can use the
-:class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\SelfValidatingPassport`.
-This class only requires a ``UserBadge`` object and optionally `Passport Badges`_.
-
-You can also pass a user loader to the ``UserBadge``. This callable receives the
-``$userIdentifier`` as argument and must return a ``UserInterface`` object
-(otherwise a ``UsernameNotFoundException`` is thrown). If this is not set, 
-the default user provider will be used with ``$userIdentifier`` as username::
-
-    // ...
-    return new SelfValidatingPassport(new UserBadge($email, function ($username) {
-        return $this->userRepository->findOneBy(['email' => $username]);
-    });
+........................
 
+If you don't need any credentials to be checked (e.g. when using API
+tokens), you can use the
+:class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\SelfValidatingPassport`.
+This class only requires a ``UserBadge`` object and optionally `Passport
+Badges`_.
 
 Passport Badges
 ~~~~~~~~~~~~~~~
@@ -511,16 +541,21 @@ the following badges are supported:
     initiated). This skips the
     :doc:`pre-authentication user checker </security/user_checkers>`.
 
-For instance, if you want to add CSRF and password migration to your custom
-authenticator, you would initialize the passport like this::
+.. versionadded:: 5.2
+
+    Since 5.2, the ``PasswordUpgradeBadge`` is automatically added to
+    the passport if the passport has ``PasswordCredentials``.
+
+For instance, if you want to add CSRF to your custom authenticator, you
+would initialize the passport like this::
 
     // src/Service/LoginAuthenticator.php
     namespace App\Service;
 
     // ...
     use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
     use Symfony\Component\Security\Http\Authenticator\Passport\Badge\CsrfTokenBadge;
-    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\PasswordUpgradeBadge;
+    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
     use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
     use Symfony\Component\Security\Http\Authenticator\Passport\PassportInterface;
 
@@ -532,14 +567,13 @@ authenticator, you would initialize the passport like this::
             $username = $request->request->get('username');
             $csrfToken = $request->request->get('csrf_token');
 
-            // ... get the $user from the $username and validate no
-            // parameter is empty
+            // ... validate no parameter is empty
 
-            return new Passport($user, new PasswordCredentials($password), [
-                // $this->userRepository must implement PasswordUpgraderInterface
-                new PasswordUpgradeBadge($password, $this->userRepository),
-                new CsrfTokenBadge('login', $csrfToken),
-            ]);
+            return new Passport(
+                new UserBadge($user),
+                new PasswordCredentials($password),
+                [new CsrfTokenBadge('login', $csrfToken)]
+            );
         }
     }