Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Security
  4. How to Impersonate a User
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Knowing When Impersonation Is Active
  • Finding the Original User
  • Controlling the Query Parameter
  • Limiting User Switching
  • Events

How to Impersonate a User

Edit this page

Warning: You are browsing the documentation for Symfony 5.1, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

How to Impersonate a User

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:

  • YAML
  • XML
  • PHP
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
18
19
<!-- 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/>
        </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 HTTP_X_SWITCH_USER header.

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

You can use the special attribute IS_IMPERSONATOR to check if the impersonation is active in this session. Use this special role, for instance, to show a link to exit impersonation in a template:

1
2
3
{% if is_granted('IS_IMPERSONATOR') %}
    <a href="{{ path('homepage', {'_switch_user': '_exit'}) }}">Exit impersonation</a>
{% endif %}

5.1

The IS_IMPERSONATOR was introduced in Symfony 5.1. Use ROLE_PREVIOUS_ADMIN prior to Symfony 5.1.

Finding the Original User

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:

  • YAML
  • XML
  • PHP
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
17
18
<!-- 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 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):

  • YAML
  • XML
  • PHP
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
17
18
<!-- 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 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/Service/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)
    {
        return in_array($attribute, ['CAN_SWITCH_USER'])
            && $subject instanceof UserInterface;
    }

    protected function voteOnAttribute($attribute, $subject, TokenInterface $token)
    {
        $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)
    {
        $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()
    {
        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.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Make sure your project is risk free

    Make sure your project is risk free

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Vico Dambeck, a Symfony contributor

    Thanks Vico Dambeck for being a Symfony contributor

    1 commit • 3 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia