feature #22048 [Security] deprecate the Role and SwitchUserRole classes (xabbuh)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[Security] deprecate the Role and SwitchUserRole classes

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #20824
| License       | MIT
| Doc PR        | symfony/symfony-docs#11047

In #20801, we deprecated the `RoleInterface`. The next logical step would be to also deprecate the `Role` class. However, we currently have the `SwitchUserRole` class (a sub-class of `Role`) that acts as an indicator to check whether or not the authenticated user switched to another user.

This PR proposes an alternative solution to the usage of the special `SwitchUserRole` class by storing the original token inside the `UsernamePasswordToken`. This PR is not complete, but rather acts as a proof of concept of how we could get rid of the `Role` and the `SwitchUserRole` classes.

Please share your opinions whether you think this is a valid approach and I will be happy to finalise the PR.

Commits
-------

d7aaa615b9 deprecate the Role and SwitchUserRole classes

Author: fabpot

Authentication/Provider/UserAuthenticationProvider.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Security\Core\Authentication\Provider;
 
+use Symfony\Component\Security\Core\Authentication\Token\SwitchUserToken;
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
 use Symfony\Component\Security\Core\Exception\AuthenticationException;
@@ -87,7 +88,12 @@ public function authenticate(TokenInterface $token)
             throw $e;
         }
 
-        $authenticatedToken = new UsernamePasswordToken($user, $token->getCredentials(), $this->providerKey, $this->getRoles($user, $token));
+        if ($token instanceof SwitchUserToken) {
+            $authenticatedToken = new SwitchUserToken($user, $token->getCredentials(), $this->providerKey, $this->getRoles($user, $token), $token->getOriginalToken());
+        } else {
+            $authenticatedToken = new UsernamePasswordToken($user, $token->getCredentials(), $this->providerKey, $this->getRoles($user, $token));
+        }
+
         $authenticatedToken->setAttributes($token->getAttributes());
 
         return $authenticatedToken;
@@ -110,7 +116,7 @@ private function getRoles(UserInterface $user, TokenInterface $token)
     {
         $roles = $user->getRoles();
 
-        foreach ($token->getRoles() as $role) {
+        foreach ($token->getRoles(false) as $role) {
             if ($role instanceof SwitchUserRole) {
                 $roles[] = $role;
 

Authentication/Token/AbstractToken.php

@@ -26,32 +26,43 @@ abstract class AbstractToken implements TokenInterface
 {
     private $user;
     private $roles = [];
+    private $roleNames = [];
     private $authenticated = false;
     private $attributes = [];
 
     /**
-     * @param (Role|string)[] $roles An array of roles
+     * @param string[] $roles An array of roles
      *
      * @throws \InvalidArgumentException
      */
     public function __construct(array $roles = [])
     {
         foreach ($roles as $role) {
             if (\is_string($role)) {
-                $role = new Role($role);
+                $role = new Role($role, false);
             } elseif (!$role instanceof Role) {
                 throw new \InvalidArgumentException(sprintf('$roles must be an array of strings, or Role instances, but got %s.', \gettype($role)));
             }
 
             $this->roles[] = $role;
+            $this->roleNames[] = (string) $role;
         }
     }
 
+    public function getRoleNames(): array
+    {
+        return $this->roleNames;
+    }
+
     /**
      * {@inheritdoc}
      */
     public function getRoles()
     {
+        if (0 === \func_num_args() || func_get_arg(0)) {
+            @trigger_error(sprintf('The %s() method is deprecated since Symfony 4.3. Use the getRoleNames() method instead.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         return $this->roles;
     }
 
@@ -172,7 +183,7 @@ public function unserialize($serialized)
      */
     protected function getState(): array
     {
-        return [$this->user, $this->authenticated, $this->roles, $this->attributes];
+        return [$this->user, $this->authenticated, $this->roles, $this->attributes, $this->roleNames];
     }
 
     /**
@@ -193,7 +204,7 @@ protected function getState(): array
      */
     protected function setState(array $data)
     {
-        [$this->user, $this->authenticated, $this->roles, $this->attributes] = $data;
+        [$this->user, $this->authenticated, $this->roles, $this->attributes, $this->roleNames] = $data;
     }
 
     /**

Authentication/Token/AnonymousToken.php

@@ -11,8 +11,6 @@
 
 namespace Symfony\Component\Security\Core\Authentication\Token;
 
-use Symfony\Component\Security\Core\Role\Role;
-
 /**
  * AnonymousToken represents an anonymous token.
  *
@@ -25,7 +23,7 @@ class AnonymousToken extends AbstractToken
     /**
      * @param string        $secret A secret used to make sure the token is created by the app and not by a malicious client
      * @param string|object $user   The user can be a UserInterface instance, or an object implementing a __toString method or the username as a regular string
-     * @param Role[]        $roles  An array of roles
+     * @param string[]      $roles  An array of roles
      */
     public function __construct(string $secret, $user, array $roles = [])
     {

Authentication/Token/PreAuthenticatedToken.php

@@ -11,8 +11,6 @@
 
 namespace Symfony\Component\Security\Core\Authentication\Token;
 
-use Symfony\Component\Security\Core\Role\Role;
-
 /**
  * PreAuthenticatedToken implements a pre-authenticated token.
  *
@@ -24,10 +22,10 @@ class PreAuthenticatedToken extends AbstractToken
     private $providerKey;
 
     /**
-     * @param string|object   $user        The user can be a UserInterface instance, or an object implementing a __toString method or the username as a regular string
-     * @param mixed           $credentials The user credentials
-     * @param string          $providerKey The provider key
-     * @param (Role|string)[] $roles       An array of roles
+     * @param string|object $user        The user can be a UserInterface instance, or an object implementing a __toString method or the username as a regular string
+     * @param mixed         $credentials The user credentials
+     * @param string        $providerKey The provider key
+     * @param string[]      $roles       An array of roles
      */
     public function __construct($user, $credentials, string $providerKey, array $roles = [])
     {

Authentication/Token/Storage/TokenStorage.php

@@ -39,6 +39,10 @@ public function getToken()
      */
     public function setToken(TokenInterface $token = null)
     {
+        if (null !== $token && !method_exists($token, 'getRoleNames')) {
+            @trigger_error(sprintf('Not implementing the getRoleNames() method in %s which implements %s is deprecated since Symfony 4.3.', \get_class($token), TokenInterface::class), E_USER_DEPRECATED);
+        }
+
         $this->token = $token;
     }
 

Authentication/Token/SwitchUserToken.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Authentication\Token;
+
+/**
+ * Token representing a user who temporarily impersonates another one.
+ *
+ * @author Christian Flothmann <[email protected]>
+ */
+class SwitchUserToken extends UsernamePasswordToken
+{
+    private $originalToken;
+
+    /**
+     * @param string|object  $user          The username (like a nickname, email address, etc.), or a UserInterface instance or an object implementing a __toString method
+     * @param mixed          $credentials   This usually is the password of the user
+     * @param string         $providerKey   The provider key
+     * @param string[]       $roles         An array of roles
+     * @param TokenInterface $originalToken The token of the user who switched to the current user
+     *
+     * @throws \InvalidArgumentException
+     */
+    public function __construct($user, $credentials, string $providerKey, array $roles = [], TokenInterface $originalToken)
+    {
+        parent::__construct($user, $credentials, $providerKey, $roles);
+
+        $this->originalToken = $originalToken;
+    }
+
+    public function getOriginalToken(): TokenInterface
+    {
+        return $this->originalToken;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getState(): array
+    {
+        return [$this->originalToken, parent::getState()];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function setState(array $data)
+    {
+        [$this->originalToken, $parentData] = $data;
+        parent::setState($parentData);
+    }
+}

Authentication/Token/TokenInterface.php

@@ -18,6 +18,8 @@
  *
  * @author Fabien Potencier <[email protected]>
  * @author Johannes M. Schmitt <[email protected]>
+ *
+ * @method string[] getRoleNames() The associated roles - not implementing it is deprecated since Symfony 4.3
  */
 interface TokenInterface extends \Serializable
 {
@@ -34,6 +36,8 @@ public function __toString();
      * Returns the user roles.
      *
      * @return Role[] An array of Role instances
+     *
+     * @deprecated since Symfony 4.3, use the getRoleNames() method instead
      */
     public function getRoles();
 

Authentication/Token/UsernamePasswordToken.php

@@ -11,8 +11,6 @@
 
 namespace Symfony\Component\Security\Core\Authentication\Token;
 
-use Symfony\Component\Security\Core\Role\Role;
-
 /**
  * UsernamePasswordToken implements a username and password token.
  *
@@ -24,10 +22,10 @@ class UsernamePasswordToken extends AbstractToken
     private $providerKey;
 
     /**
-     * @param string|object   $user        The username (like a nickname, email address, etc.), or a UserInterface instance or an object implementing a __toString method
-     * @param mixed           $credentials This usually is the password of the user
-     * @param string          $providerKey The provider key
-     * @param (Role|string)[] $roles       An array of roles
+     * @param string|object $user        The username (like a nickname, email address, etc.), or a UserInterface instance or an object implementing a __toString method
+     * @param mixed         $credentials This usually is the password of the user
+     * @param string        $providerKey The provider key
+     * @param string[]      $roles       An array of roles
      *
      * @throws \InvalidArgumentException
      */

Authorization/Voter/ExpressionVoter.php

@@ -18,6 +18,8 @@
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
 use Symfony\Component\Security\Core\Authorization\ExpressionLanguage;
+use Symfony\Component\Security\Core\Role\Role;
+use Symfony\Component\Security\Core\Role\RoleHierarchy;
 use Symfony\Component\Security\Core\Role\RoleHierarchyInterface;
 
 /**
@@ -90,18 +92,34 @@ public function vote(TokenInterface $token, $subject, array $attributes)
 
     private function getVariables(TokenInterface $token, $subject)
     {
-        if (null !== $this->roleHierarchy) {
-            $roles = $this->roleHierarchy->getReachableRoles($token->getRoles());
+        if ($this->roleHierarchy instanceof RoleHierarchy) {
+            if (method_exists($token, 'getRoleNames')) {
+                $rolesFromToken = $token->getRoleNames();
+            } else {
+                @trigger_error(sprintf('Not implementing the getRoleNames() method in %s which implements %s is deprecated since Symfony 4.3.', \get_class($token), TokenInterface::class), E_USER_DEPRECATED);
+
+                $rolesFromToken = $token->getRoles(false);
+            }
+
+            $roles = $this->roleHierarchy->getReachableRoleNames($rolesFromToken);
+        } elseif (null !== $this->roleHierarchy) {
+            $roles = $this->roleHierarchy->getReachableRoles($token->getRoles(false));
+        } elseif (method_exists($token, 'getRoleNames')) {
+            $roles = $token->getRoleNames();
         } else {
-            $roles = $token->getRoles();
+            @trigger_error(sprintf('Not implementing the getRoleNames() method in %s which implements %s is deprecated since Symfony 4.3.', \get_class($token), TokenInterface::class), E_USER_DEPRECATED);
+
+            $roles = $token->getRoles(false);
         }
 
+        $roles = array_map(function ($role) { return $role instanceof Role ? $role->getRole() : $role; }, $roles);
+
         $variables = [
             'token' => $token,
             'user' => $token->getUser(),
             'object' => $subject,
             'subject' => $subject,
-            'roles' => array_map(function ($role) { return $role->getRole(); }, $roles),
+            'roles' => $roles,
             'trust_resolver' => $this->trustResolver,
             'auth_checker' => $this->authChecker,
         ];

Authorization/Voter/RoleHierarchyVoter.php

@@ -12,6 +12,7 @@
 namespace Symfony\Component\Security\Core\Authorization\Voter;
 
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\Security\Core\Role\RoleHierarchy;
 use Symfony\Component\Security\Core\Role\RoleHierarchyInterface;
 
 /**
@@ -26,6 +27,10 @@ class RoleHierarchyVoter extends RoleVoter
 
     public function __construct(RoleHierarchyInterface $roleHierarchy, string $prefix = 'ROLE_')
     {
+        if (!$roleHierarchy instanceof RoleHierarchy) {
+            @trigger_error(sprintf('Passing a role hierarchy to "%s" that is not an instance of "%s" is deprecated since Symfony 4.3 and support for it will be dropped in Symfony 5.0 ("%s" given).', __CLASS__, RoleHierarchy::class, \get_class($roleHierarchy)), E_USER_DEPRECATED);
+        }
+
         $this->roleHierarchy = $roleHierarchy;
 
         parent::__construct($prefix);
@@ -36,6 +41,18 @@ public function __construct(RoleHierarchyInterface $roleHierarchy, string $prefi
      */
     protected function extractRoles(TokenInterface $token)
     {
-        return $this->roleHierarchy->getReachableRoles($token->getRoles());
+        if ($this->roleHierarchy instanceof RoleHierarchy) {
+            if (method_exists($token, 'getRoleNames')) {
+                $roles = $token->getRoleNames();
+            } else {
+                @trigger_error(sprintf('Not implementing the getRoleNames() method in %s which implements %s is deprecated since Symfony 4.3.', \get_class($token), TokenInterface::class), E_USER_DEPRECATED);
+
+                $roles = $token->getRoles(false);
+            }
+
+            return $this->roleHierarchy->getReachableRoleNames($roles);
+        }
+
+        return $this->roleHierarchy->getReachableRoles($token->getRoles(false));
     }
 }

Authorization/Voter/RoleVoter.php

@@ -47,7 +47,7 @@ public function vote(TokenInterface $token, $subject, array $attributes)
 
             $result = VoterInterface::ACCESS_DENIED;
             foreach ($roles as $role) {
-                if ($attribute === $role->getRole()) {
+                if ($attribute === $role) {
                     return VoterInterface::ACCESS_GRANTED;
                 }
             }
@@ -58,6 +58,12 @@ public function vote(TokenInterface $token, $subject, array $attributes)
 
     protected function extractRoles(TokenInterface $token)
     {
-        return $token->getRoles();
+        if (method_exists($token, 'getRoleNames')) {
+            return $token->getRoleNames();
+        }
+
+        @trigger_error(sprintf('Not implementing the getRoleNames() method in %s which implements %s is deprecated since Symfony 4.3.', \get_class($token), TokenInterface::class), E_USER_DEPRECATED);
+
+        return array_map(function (Role $role) { return $role->getRole(); }, $token->getRoles(false));
     }
 }

Role/Role.php

@@ -15,13 +15,19 @@
  * Role is a simple implementation representing a role identified by a string.
  *
  * @author Fabien Potencier <[email protected]>
+ *
+ * @deprecated since Symfony 4.3, to be removed in 5.0. Use strings as roles instead.
  */
 class Role
 {
     private $role;
 
     public function __construct(string $role)
     {
+        if (\func_num_args() < 2 || func_get_arg(1)) {
+            @trigger_error(sprintf('The "%s" class is deprecated since Symfony 4.3 and will be removed in 5.0. Use strings as roles instead.', __CLASS__), E_USER_DEPRECATED);
+        }
+
         $this->role = $role;
     }
 
@@ -34,4 +40,9 @@ public function getRole()
     {
         return $this->role;
     }
+
+    public function __toString(): string
+    {
+        return $this->role;
+    }
 }