minor #40672 [Security] [Passport] improve dx and document Authentica…

…tionException (jrushlow)

This PR was merged into the 5.2 branch.

Discussion
----------

[Security] [Passport] improve dx and document AuthenticationException

| Q             | A
| ------------- | ---
| Branch?       | 5.2
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | N/A
| License       | MIT
| Doc PR        | tbd

`Passport::getUser()` (Instance of `UserPassportInterface::class`) throws an `AuthenticationException::class`
 if a user does not exist. Let's document that for better DX and visibility.

Use case:

- User login w/ a `username` that does not exist (custom json authenticator)
- Attempt Authentication...
- Auth failed `LoginFailureEvent` dispatched
- snippet below:
```php
// Userland\LoginFailureEventSubscriber::class

public function dispatchFailure(LoginFailureEvent $event): void
{
   $user = $event->getPassport()->getUser();

   $message = new UserlandMessage($user);

  $this->messageBus->dispatch($message);
}
```
- `401` status is returned.

The above subscriber fails silently because a `UsernameNotFoundException` was ultimately thrown from `UserBadge::getUser()`.

Commits
-------

97ceba0f5d improve dx and document auth exception

Authenticator/Passport/Badge/UserBadge.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Security\Http\Authenticator\Passport\Badge;
 
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
 use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
 use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Component\Security\Http\EventListener\UserProviderListener;
@@ -55,6 +56,9 @@ public function getUserIdentifier(): string
         return $this->userIdentifier;
     }
 
+    /**
+     * @throws AuthenticationException when the user cannot be found
+     */
     public function getUser(): UserInterface
     {
         if (null === $this->user) {

Authenticator/Passport/Passport.php

@@ -55,6 +55,9 @@ public function __construct($userBadge, CredentialsInterface $credentials, array
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getUser(): UserInterface
     {
         if (null === $this->user) {

Authenticator/Passport/UserPassportInterface.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Security\Http\Authenticator\Passport;
 
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
 use Symfony\Component\Security\Core\User\UserInterface;
 
 /**
@@ -22,5 +23,8 @@
  */
 interface UserPassportInterface extends PassportInterface
 {
+    /**
+     * @throws AuthenticationException when the user cannot be found
+     */
     public function getUser(): UserInterface;
 }