How to Impersonate a User
Warning: You are browsing the documentation for Symfony 4.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
Sometimes, it's useful to be able to switch from one user to another without having to log out and log in again (for instance when you are debugging something a user sees that you can't reproduce).
Caution
User impersonation is not compatible with some authentication mechanisms
(e.g. REMOTE_USER
) where the authentication information is expected to be
sent on each request.
Impersonating the user can be done by activating the switch_user
firewall
listener:
1 2 3 4 5 6 7 8
# config/packages/security.yaml
security:
# ...
firewalls:
main:
# ...
switch_user: true
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd">
<config>
<!-- ... -->
<firewall name="main">
<!-- ... -->
<switch-user/>
</firewall>
</config>
</srv:container>
1 2 3 4 5 6 7 8 9 10 11
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main'=> [
// ...
'switch_user' => true,
],
],
]);
To switch to another user, add a query string with the _switch_user
parameter and the username (or whatever field our user provider uses to load users)
as the value to the current URL:
1
http://example.com/somewhere?_switch_user=thomas
Tip
Instead of adding a _switch_user
query string parameter, you can pass
the username in a custom HTTP header by adjusting the parameter
setting.
For example, to use X-Switch-User
header (available in PHP as
HTTP_X_SWITCH_USER
) add this configuration:
1 2 3 4 5 6 7
# config/packages/security.yaml
security:
# ...
firewalls:
main:
# ...
switch_user: { parameter: X-Switch-User }
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/security
https://symfony.com/schema/dic/security/security-1.0.xsd">
<config>
<!-- ... -->
<firewall name="main">
<!-- ... -->
<switch-user parameter="X-Switch-User"/>
</firewall>
</config>
</srv:container>
1 2 3 4 5 6 7 8 9 10
// config/packages/security.php
use Symfony\Config\SecurityConfig;
return static function (SecurityConfig $security) {
// ...
$security->firewall('main')
// ...
->switchUser()
->parameter('X-Switch-User')
;
};
To switch back to the original user, use the special _exit
username:
1
http://example.com/somewhere?_switch_user=_exit
This feature is only available to users with a special role called ROLE_ALLOWED_TO_SWITCH
.
Using role_hierarchy is a great way to give this
role to the users that need it.
Knowing When Impersonation Is Active
When a user is being impersonated, Symfony grants them a special role called
ROLE_PREVIOUS_ADMIN
(in addition to the roles the user may have). Use this
special role, for instance, to show a link to exit impersonation in a template:
1 2 3
{% if is_granted('ROLE_PREVIOUS_ADMIN') %}
<a href="{{ path('homepage', {'_switch_user': '_exit'}) }}">Exit impersonation</a>
{% endif %}
Finding the Original User
4.3
The SwitchUserToken
class was introduced in Symfony 4.3.
In some cases, you may need to get the object that represents the impersonator
user rather than the impersonated user. When a user is impersonated the token
stored in the token storage will be a SwitchUserToken
instance. Use the
following snippet to obtain the original token which gives you access to
the impersonator user:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
// src/Service/SomeService.php
namespace App\Service;
use Symfony\Component\Security\Core\Authentication\Token\SwitchUserToken;
use Symfony\Component\Security\Core\Security;
// ...
class SomeService
{
private $security;
public function __construct(Security $security)
{
$this->security = $security;
}
public function someMethod()
{
// ...
$token = $this->security->getToken();
if ($token instanceof SwitchUserToken) {
$impersonatorUser = $token->getOriginalToken()->getUser();
}
// ...
}
}
Controlling the Query Parameter
This feature needs to be available only to a restricted group of users.
By default, access is restricted to users having the ROLE_ALLOWED_TO_SWITCH
role. The name of this role can be modified via the role
setting. You can
also adjust the query parameter name via the parameter
setting:
1 2 3 4 5 6 7 8
# config/packages/security.yaml
security:
# ...
firewalls:
main:
# ...
switch_user: { role: ROLE_ADMIN, parameter: _want_to_be_this_user }
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd">
<config>
<!-- ... -->
<firewall name="main">
<!-- ... -->
<switch-user role="ROLE_ADMIN" parameter="_want_to_be_this_user"/>
</firewall>
</config>
</srv:container>
1 2 3 4 5 6 7 8 9 10 11 12 13 14
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main'=> [
// ...
'switch_user' => [
'role' => 'ROLE_ADMIN',
'parameter' => '_want_to_be_this_user',
],
],
],
]);
Limiting User Switching
If you need more control over user switching, you can use a security voter. First,
configure switch_user
to check for some new, custom attribute. This can be
anything, but cannot start with ROLE_
(to enforce that only your voter will
be called):
1 2 3 4 5 6 7 8
# config/packages/security.yaml
security:
# ...
firewalls:
main:
# ...
switch_user: { role: CAN_SWITCH_USER }
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd">
<config>
<!-- ... -->
<firewall name="main">
<!-- ... -->
<switch-user role="CAN_SWITCH_USER"/>
</firewall>
</config>
</srv:container>
1 2 3 4 5 6 7 8 9 10 11 12 13
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main'=> [
// ...
'switch_user' => [
'role' => 'CAN_SWITCH_USER',
],
],
],
]);
Then, create a voter class that responds to this role and includes whatever custom logic you want:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
// src/Security/Voter/SwitchToCustomerVoter.php
namespace App\Security\Voter;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Authorization\Voter\Voter;
use Symfony\Component\Security\Core\Security;
use Symfony\Component\Security\Core\User\UserInterface;
class SwitchToCustomerVoter extends Voter
{
private $security;
public function __construct(Security $security)
{
$this->security = $security;
}
protected function supports($attribute, $subject): bool
{
return in_array($attribute, ['CAN_SWITCH_USER'])
&& $subject instanceof UserInterface;
}
protected function voteOnAttribute($attribute, $subject, TokenInterface $token): bool
{
$user = $token->getUser();
// if the user is anonymous or if the subject is not a user, do not grant access
if (!$user instanceof UserInterface || !$subject instanceof UserInterface) {
return false;
}
// you can still check for ROLE_ALLOWED_TO_SWITCH
if ($this->security->isGranted('ROLE_ALLOWED_TO_SWITCH')) {
return true;
}
// check for any roles you want
if ($this->security->isGranted('ROLE_TECH_SUPPORT')) {
return true;
}
/*
* or use some custom data from your User object
if ($user->isAllowedToSwitch()) {
return true;
}
*/
return false;
}
}
That's it! When switching users, your voter now has full control over whether or not this is allowed. If your voter isn't called, see How to Use Voters to Check User Permissions.
Events
The firewall dispatches the security.switch_user
event right after the impersonation
is completed. The SwitchUserEvent is
passed to the listener, and you can use this to get the user that you are now impersonating.
The Making the Locale "Sticky" during a User's Session article does not update the locale when you impersonate a user. If you do want to be sure to update the locale when you switch users, add an event subscriber on this event:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
// src/EventListener/SwitchUserSubscriber.php
namespace App\EventListener;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Security\Http\Event\SwitchUserEvent;
use Symfony\Component\Security\Http\SecurityEvents;
class SwitchUserSubscriber implements EventSubscriberInterface
{
public function onSwitchUser(SwitchUserEvent $event): void
{
$request = $event->getRequest();
if ($request->hasSession() && ($session = $request->getSession())) {
$session->set(
'_locale',
// assuming your User has some getLocale() method
$event->getTargetUser()->getLocale()
);
}
}
public static function getSubscribedEvents(): array
{
return [
// constant for security.switch_user
SecurityEvents::SWITCH_USER => 'onSwitchUser',
];
}
}
That's it! If you're using the default services.yaml configuration,
Symfony will automatically discover your service and call onSwitchUser
whenever
a switch user occurs.
For more details about event subscribers, see Events and Event Listeners.