[Security] Rename UserInterface::getUsername() to getUserIdentifier()

Author: wouterj

Authentication/AuthenticationProviderManager.php

@@ -21,6 +21,7 @@
 use Symfony\Component\Security\Core\Exception\AuthenticationException;
 use Symfony\Component\Security\Core\Exception\BadCredentialsException;
 use Symfony\Component\Security\Core\Exception\ProviderNotFoundException;
+use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
 // Help opcache.preload discover always-needed symbols
@@ -105,6 +106,11 @@ public function authenticate(TokenInterface $token)
                 $this->eventDispatcher->dispatch(new AuthenticationSuccessEvent($result), AuthenticationEvents::AUTHENTICATION_SUCCESS);
             }
 
+            // @deprecated since 5.3
+            if ($user = $result->getUser() instanceof UserInterface && !method_exists($result->getUser(), 'getUserIdentifier')) {
+                trigger_deprecation('symfony/security-core', '5.3', 'Not implementing method "getUserIdentifier(): string" in user class "%s" is deprecated. This method will replace "getUsername()" in Symfony 6.0.', get_debug_type($result->getUser()));
+            }
+
             return $result;
         }
 

Authentication/Provider/DaoAuthenticationProvider.php

@@ -16,7 +16,7 @@
 use Symfony\Component\Security\Core\Encoder\EncoderFactoryInterface;
 use Symfony\Component\Security\Core\Exception\AuthenticationServiceException;
 use Symfony\Component\Security\Core\Exception\BadCredentialsException;
-use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
+use Symfony\Component\Security\Core\Exception\UserNotFoundException;
 use Symfony\Component\Security\Core\User\LegacyPasswordAuthenticatedUserInterface;
 use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
 use Symfony\Component\Security\Core\User\PasswordUpgraderInterface;
@@ -108,23 +108,30 @@ protected function checkAuthentication(UserInterface $user, UsernamePasswordToke
     /**
      * {@inheritdoc}
      */
-    protected function retrieveUser(string $username, UsernamePasswordToken $token)
+    protected function retrieveUser(string $userIdentifier, UsernamePasswordToken $token)
     {
         $user = $token->getUser();
         if ($user instanceof UserInterface) {
             return $user;
         }
 
         try {
-            $user = $this->userProvider->loadUserByUsername($username);
+            // @deprecated since 5.3, change to $this->userProvider->loadUserByIdentifier() in 6.0
+            if (method_exists($this->userProvider, 'loadUserByIdentifier')) {
+                $user = $this->userProvider->loadUserByIdentifier($userIdentifier);
+            } else {
+                trigger_deprecation('symfony/security-core', '5.3', 'Not implementing method "loadUserByIdentifier()" in user provider "%s" is deprecated. This method will replace "loadUserByUsername()" in Symfony 6.0.', get_debug_type($this->userProvider));
+
+                $user = $this->userProvider->loadUserByUsername($userIdentifier);
+            }
 
             if (!$user instanceof UserInterface) {
                 throw new AuthenticationServiceException('The user provider must return a UserInterface object.');
             }
 
             return $user;
-        } catch (UsernameNotFoundException $e) {
-            $e->setUsername($username);
+        } catch (UserNotFoundException $e) {
+            $e->setUserIdentifier($userIdentifier);
             throw $e;
         } catch (\Exception $e) {
             $e = new AuthenticationServiceException($e->getMessage(), 0, $e);

Authentication/Provider/LdapBindAuthenticationProvider.php

@@ -16,7 +16,7 @@
 use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
 use Symfony\Component\Security\Core\Exception\BadCredentialsException;
 use Symfony\Component\Security\Core\Exception\LogicException;
-use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
+use Symfony\Component\Security\Core\Exception\UserNotFoundException;
 use Symfony\Component\Security\Core\User\UserCheckerInterface;
 use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Component\Security\Core\User\UserProviderInterface;
@@ -38,7 +38,7 @@ class LdapBindAuthenticationProvider extends UserAuthenticationProvider
     private $searchDn;
     private $searchPassword;
 
-    public function __construct(UserProviderInterface $userProvider, UserCheckerInterface $userChecker, string $providerKey, LdapInterface $ldap, string $dnString = '{username}', bool $hideUserNotFoundExceptions = true, string $searchDn = '', string $searchPassword = '')
+    public function __construct(UserProviderInterface $userProvider, UserCheckerInterface $userChecker, string $providerKey, LdapInterface $ldap, string $dnString = '{user_identifier}', bool $hideUserNotFoundExceptions = true, string $searchDn = '', string $searchPassword = '')
     {
         parent::__construct($userChecker, $providerKey, $hideUserNotFoundExceptions);
 
@@ -50,7 +50,7 @@ public function __construct(UserProviderInterface $userProvider, UserCheckerInte
     }
 
     /**
-     * Set a query string to use in order to find a DN for the username.
+     * Set a query string to use in order to find a DN for the user identifier.
      */
     public function setQueryString(string $queryString)
     {
@@ -60,21 +60,29 @@ public function setQueryString(string $queryString)
     /**
      * {@inheritdoc}
      */
-    protected function retrieveUser(string $username, UsernamePasswordToken $token)
+    protected function retrieveUser(string $userIdentifier, UsernamePasswordToken $token)
     {
-        if (AuthenticationProviderInterface::USERNAME_NONE_PROVIDED === $username) {
-            throw new UsernameNotFoundException('Username can not be null.');
+        if (AuthenticationProviderInterface::USERNAME_NONE_PROVIDED === $userIdentifier) {
+            throw new UserNotFoundException('User identifier can not be null.');
         }
 
-        return $this->userProvider->loadUserByUsername($username);
+        // @deprecated since 5.3, change to $this->userProvider->loadUserByIdentifier() in 6.0
+        if (method_exists($this->userProvider, 'loadUserByIdentifier')) {
+            return $this->userProvider->loadUserByIdentifier($userIdentifier);
+        } else {
+            trigger_deprecation('symfony/security-core', '5.3', 'Not implementing method "loadUserByIdentifier()" in user provider "%s" is deprecated. This method will replace "loadUserByUsername()" in Symfony 6.0.', get_debug_type($this->userProvider));
+
+            return $this->userProvider->loadUserByUsername($userIdentifier);
+        }
     }
 
     /**
      * {@inheritdoc}
      */
     protected function checkAuthentication(UserInterface $user, UsernamePasswordToken $token)
     {
-        $username = $token->getUsername();
+        // @deprecated since 5.3, change to $token->getUserIdentifier() in 6.0
+        $userIdentifier = method_exists($token, 'getUserIdentifier') ? $token->getUserIdentifier() : $token->getUsername();
         $password = $token->getCredentials();
 
         if ('' === (string) $password) {
@@ -88,17 +96,17 @@ protected function checkAuthentication(UserInterface $user, UsernamePasswordToke
                 } else {
                     throw new LogicException('Using the "query_string" config without using a "search_dn" and a "search_password" is not supported.');
                 }
-                $username = $this->ldap->escape($username, '', LdapInterface::ESCAPE_FILTER);
-                $query = str_replace('{username}', $username, $this->queryString);
+                $userIdentifier = $this->ldap->escape($userIdentifier, '', LdapInterface::ESCAPE_FILTER);
+                $query = str_replace(['{username}', '{user_identifier}'], $userIdentifier, $this->queryString);
                 $result = $this->ldap->query($this->dnString, $query)->execute();
                 if (1 !== $result->count()) {
                     throw new BadCredentialsException('The presented username is invalid.');
                 }
 
                 $dn = $result[0]->getDn();
             } else {
-                $username = $this->ldap->escape($username, '', LdapInterface::ESCAPE_DN);
-                $dn = str_replace('{username}', $username, $this->dnString);
+                $userIdentifier = $this->ldap->escape($userIdentifier, '', LdapInterface::ESCAPE_DN);
+                $dn = str_replace(['{username}', '{user_identifier}'], $userIdentifier, $this->dnString);
             }
 
             $this->ldap->bind($dn, $password);

Authentication/Provider/PreAuthenticatedAuthenticationProvider.php

@@ -24,7 +24,7 @@
  * This authentication provider will not perform any checks on authentication
  * requests, as they should already be pre-authenticated. However, the
  * UserProviderInterface implementation may still throw a
- * UsernameNotFoundException, for example.
+ * UserNotFoundException, for example.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
@@ -54,7 +54,15 @@ public function authenticate(TokenInterface $token)
             throw new BadCredentialsException('No pre-authenticated principal found in request.');
         }
 
-        $user = $this->userProvider->loadUserByUsername($user);
+        $userIdentifier = method_exists($token, 'getUserIdentifier') ? $token->getUserIdentifier() : $token->getUsername();
+        // @deprecated since 5.3, change to $this->userProvider->loadUserByIdentifier() in 6.0
+        if (method_exists($this->userProvider, 'loadUserByIdentifier')) {
+            $user = $this->userProvider->loadUserByIdentifier($userIdentifier);
+        } else {
+            trigger_deprecation('symfony/security-core', '5.3', 'Not implementing method "loadUserByIdentifier()" in user provider "%s" is deprecated. This method will replace "loadUserByUsername()" in Symfony 6.0.', get_debug_type($this->userProvider));
+
+            $user = $this->userProvider->loadUserByUsername($userIdentifier);
+        }
 
         $this->userChecker->checkPostAuth($user);
 

Authentication/Provider/RememberMeAuthenticationProvider.php

@@ -51,7 +51,7 @@ public function authenticate(TokenInterface $token)
 
         $user = $token->getUser();
 
-        if (!$token->getUser() instanceof UserInterface) {
+        if (!$user instanceof UserInterface) {
             throw new LogicException(sprintf('Method "%s::getUser()" must return a "%s" instance, "%s" returned.', get_debug_type($token), UserInterface::class, get_debug_type($user)));
         }
 

Authentication/Provider/UserAuthenticationProvider.php

@@ -17,7 +17,7 @@
 use Symfony\Component\Security\Core\Exception\AuthenticationException;
 use Symfony\Component\Security\Core\Exception\AuthenticationServiceException;
 use Symfony\Component\Security\Core\Exception\BadCredentialsException;
-use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
+use Symfony\Component\Security\Core\Exception\UserNotFoundException;
 use Symfony\Component\Security\Core\User\UserCheckerInterface;
 use Symfony\Component\Security\Core\User\UserInterface;
 
@@ -55,18 +55,18 @@ public function authenticate(TokenInterface $token)
             throw new AuthenticationException('The token is not supported by this authentication provider.');
         }
 
-        $username = $token->getUsername();
+        $username = method_exists($token, 'getUserIdentifier') ? $token->getUserIdentifier() : $token->getUsername();
         if ('' === $username || null === $username) {
             $username = AuthenticationProviderInterface::USERNAME_NONE_PROVIDED;
         }
 
         try {
             $user = $this->retrieveUser($username, $token);
-        } catch (UsernameNotFoundException $e) {
+        } catch (UserNotFoundException $e) {
             if ($this->hideUserNotFoundExceptions) {
                 throw new BadCredentialsException('Bad credentials.', 0, $e);
             }
-            $e->setUsername($username);
+            $e->setUserIdentifier($username);
 
             throw $e;
         }

Authentication/RememberMe/InMemoryTokenProvider.php

@@ -45,7 +45,7 @@ public function updateToken(string $series, string $tokenValue, \DateTime $lastU
 
         $token = new PersistentToken(
             $this->tokens[$series]->getClass(),
-            $this->tokens[$series]->getUsername(),
+            method_exists($this->tokens[$series], 'getUserIdentifier') ? $this->tokens[$series]->getUserIdentifier() : $this->tokens[$series]->getUsername(),
             $series,
             $tokenValue,
             $lastUsed

Authentication/RememberMe/PersistentToken.php

@@ -19,18 +19,18 @@
 final class PersistentToken implements PersistentTokenInterface
 {
     private $class;
-    private $username;
+    private $userIdentifier;
     private $series;
     private $tokenValue;
     private $lastUsed;
 
-    public function __construct(string $class, string $username, string $series, string $tokenValue, \DateTime $lastUsed)
+    public function __construct(string $class, string $userIdentifier, string $series, string $tokenValue, \DateTime $lastUsed)
     {
         if (empty($class)) {
             throw new \InvalidArgumentException('$class must not be empty.');
         }
-        if ('' === $username) {
-            throw new \InvalidArgumentException('$username must not be empty.');
+        if ('' === $userIdentifier) {
+            throw new \InvalidArgumentException('$userIdentifier must not be empty.');
         }
         if (empty($series)) {
             throw new \InvalidArgumentException('$series must not be empty.');
@@ -40,7 +40,7 @@ public function __construct(string $class, string $username, string $series, str
         }
 
         $this->class = $class;
-        $this->username = $username;
+        $this->userIdentifier = $userIdentifier;
         $this->series = $series;
         $this->tokenValue = $tokenValue;
         $this->lastUsed = $lastUsed;
@@ -59,7 +59,14 @@ public function getClass(): string
      */
     public function getUsername(): string
     {
-        return $this->username;
+        trigger_deprecation('symfony/security-core', '5.3', 'Method "%s()" is deprecated, use getUserIdentifier() instead.', __METHOD__);
+
+        return $this->userIdentifier;
+    }
+
+    public function getUserIdentifier(): string
+    {
+        return $this->userIdentifier;
     }
 
     /**

Authentication/RememberMe/PersistentTokenInterface.php

@@ -15,6 +15,8 @@
  * Interface to be implemented by persistent token classes (such as
  * Doctrine entities representing a remember-me token).
  *
+ * @method string getUserIdentifier() returns the identifier used to authenticate (e.g. their e-mailaddress or username)
+ *
  * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  */
 interface PersistentTokenInterface
@@ -26,13 +28,6 @@ interface PersistentTokenInterface
      */
     public function getClass();
 
-    /**
-     * Returns the username.
-     *
-     * @return string
-     */
-    public function getUsername();
-
     /**
      * Returns the series.
      *

Authentication/Token/AbstractToken.php

@@ -51,10 +51,32 @@ public function getRoleNames(): array
     /**
      * {@inheritdoc}
      */
-    public function getUsername()
+    public function getUsername(/* $legacy = true */)
     {
+        if (1 === func_num_args() && false === func_get_arg(0)) {
+            return null;
+        }
+
+        trigger_deprecation('symfony/security-core', '5.3', 'Method "%s()" is deprecated, use getUserIdentifier() instead.', __METHOD__);
+
+        if ($this->user instanceof UserInterface) {
+            return method_exists($this->user, 'getUserIdentifier') ? $this->user->getUserIdentifier() : $this->user->getUsername();
+        }
+
+        return (string) $this->user;
+    }
+
+    public function getUserIdentifier(): string
+    {
+        // method returns "null" in non-legacy mode if not overriden
+        $username = $this->getUsername(false);
+        if (null !== $username) {
+            trigger_deprecation('symfony/security-core', '5.3', 'Method "%s::getUsername()" is deprecated, override "getUserIdentifier()" instead.', get_debug_type($this));
+        }
+
         if ($this->user instanceof UserInterface) {
-            return $this->user->getUsername();
+            // @deprecated since 5.3, change to $user->getUserIdentifier() in 6.0
+            return method_exists($this->user, 'getUserIdentifier') ? $this->user->getUserIdentifier() : $this->user->getUsername();
         }
 
         return (string) $this->user;
@@ -234,7 +256,7 @@ public function __toString()
             $roles[] = $role;
         }
 
-        return sprintf('%s(user="%s", authenticated=%s, roles="%s")', $class, $this->getUsername(), json_encode($this->authenticated), implode(', ', $roles));
+        return sprintf('%s(user="%s", authenticated=%s, roles="%s")', $class, $this->getUserIdentifier(), json_encode($this->authenticated), implode(', ', $roles));
     }
 
     /**
@@ -283,7 +305,11 @@ private function hasUserChanged(UserInterface $user): bool
             return true;
         }
 
-        if ($this->user->getUsername() !== $user->getUsername()) {
+        // @deprecated since Symfony 5.3, drop getUsername() in 6.0
+        $userIdentifier = function ($user) {
+            return method_exists($user, 'getUserIdentifier') ? $user->getUserIdentifier() : $user->getUsername();
+        };
+        if ($userIdentifier($this->user) !== $userIdentifier($user)) {
             return true;
         }