Impersonation Bundle Laravel Package

Getting Started

• Know what you're installing first. nti/impersonation-bundle is a Symfony2 bundle, not a Laravel package. There is no service provider, no facade, no config/impersonation.php. If you're on Laravel, you cannot composer require this and expect it to boot — treat it as a reference implementation to mine for the impersonation workflow, then implement the equivalent with Laravel's Auth::login($user) / Auth::loginUsingId() plus a session flag.
• On Symfony2 (the intended host): require it, register Nti\ImpersonationBundle\NtiImpersonationBundle in AppKernel, and read Resources/config/ and the DependencyInjection/ extension before touching your firewall — that is where the actual wiring lives.
• Look at the firewall before the bundle. Symfony's built-in impersonation is the switch_user listener on your firewall. The bundle is a thin convenience layer on top of it. Confirm your firewall has switch_user: true and that your admin role has ROLE_ALLOWED_TO_SWITCH; without that, nothing in the bundle will work.
• First use case: an admin/support user opens a customer's record, clicks "Impersonate", and is now authenticated as that customer with a visible banner offering "Return to admin". Implement the exit path (?_switch_user=_exit) on day one — it is the part people forget.
• Version reality check: last release 2019-04-02, 1 star, 0 dependents. Budget an afternoon to read the source; do not assume the README is complete or that it supports anything past Symfony 2.x.

Implementation Patterns

• Role-gated switch, never a raw user ID from the request. Gate the switch action behind an authorization check (Symfony voters / Laravel policies or gates) and only then redirect to the firewall URL with _switch_user=<username>. Never let the target user be chosen without an explicit permission check on the actor.
• Banner + exit as a first-class UI component. Put an IS_IMPERSONATOR (or session-flag) check in your base layout so every page renders "You are acting as X — [Return]". This is the single highest-value pattern in the whole assessment: impersonation without an always-visible exit is how people file tickets as customers by accident.
• Audit every transition. Wrap the switch and exit in event listeners (Symfony kernel.event_listener / Laravel event + listener) that log actor ID, target ID, timestamp, IP, and the originating ticket/order ID. The bundle gives you the mechanism; it does not give you the audit trail.
• Keep the actor recoverable. Symfony's switch_user stores the original token in the session; on exit it restores it. Mirror that in Laravel by stashing Auth::id() in the session (impersonator_id) at login time and restoring it on exit — never Auth::logout() the customer and hope the admin session survived.
• Scope the switch to non-privileged targets. Allow impersonating customers, block impersonating other admins or anyone with ROLE_ADMIN/ROLE_SUPER_ADMIN. Add an explicit deny in the authorization layer; do not rely on the firewall config alone.
• Integrate at the controller/action boundary, not in templates. The bundle is a redirect-based flow. Call it from a controller action behind a CSRF-protected POST (or a signed GET), so the impersonation link can't be triggered by a stray <img> or a link prefetcher.
• Test the exit path and the "already impersonating" path. Two tests worth writing: switching back restores the original actor's full role set, and a second switch while impersonating is either blocked or nests cleanly (decide which, then enforce it).

Gotchas and Tips

• Symfony2 ≠ Laravel ≠ modern Symfony. The bundle targets a framework generation that is end-of-life. It will not drop into Symfony 4/5/6+ (bundle-less architecture, autowiring, security.yaml) without porting. If you're on Laravel, the honest recommendation is: read it, copy the concept, write ~50 lines yourself.
• ROLE_ALLOWED_TO_SWITCH belongs to the impersonator, not the target. This is the #1 confusion. The admin's role hierarchy must grant it; granting it to the customer does nothing.
• Firewall name matters. _switch_user only works on the firewall that has switch_user enabled. If your app has separate admin and main firewalls, switching across them silently fails or logs you out.
• Session and token refresh. After switching, anything cached from the old token (user object in a service, a memoized $this->getUser(), a cached navigation menu built for the previous user) is stale. Force a redirect after switch — don't render in the same request.
• Remember-me and logout. If the target user has a remember-me cookie flow, switching can muddy it. Verify logout while impersonating logs out the customer and returns the admin cleanly, or blocks — pick one and document it.
• Debugging checklist: (1) is switch_user: true on the right firewall, (2) does the actor have ROLE_ALLOWED_TO_SWITCH, (3) does the URL carry the correct _switch_user value and the firewall's context, (4) is the security token actually rewritten (dump it), (5) is the exit link _switch_user=_exit.
• Don't enable in production without an allowlist and audit. Impersonation is a privilege-escalation primitive. Restrict to specific roles, log everything, and consider an expiry (auto-exit after N minutes) — the bundle does not give you that.
• No maintained support surface. With 1 star, 0 dependents, and a 2019 release, there is no community to lean on. Pin the exact version, vendor the source if you rely on it, and keep the diff small so you can replace it later.