laranail/impersonator

laranail/impersonator is not published to Packagist, so there is no registry-version badge to show: see Install.

Laravel user impersonation with pluggable drivers and auth adapters, privilege-scoped impersonation modes, two-level audit trails, RBAC integration, remote revocation, break-glass approvals, and an optional REST API.

Requires PHP 8.4.1+ and Laravel 13. Hard dependencies are illuminate/*, three PSR interfaces, and four laranail/* packages. Sanctum, Passport, JWT, stancl/tenancy and spatie/laravel-permission are all optional — install one and its integration activates itself.

Install

composer require laranail/impersonator

The laranail/* family resolves through git rather than Packagist, so the closure has to be declared in your root composer.json first — see Installation.

php artisan vendor:publish --tag=laranail::impersonator-config
php artisan vendor:publish --tag=laranail::impersonator-migrations
php artisan vendor:publish --tag=laranail::impersonator-lang       # optional: reword or translate
php artisan migrate

Then name your user model, which is the one setting that has no sensible default:

// config/laranail/impersonator.php
'targets' => [
    'allowlist' => ['user' => App\Models\User::class],
],

Quick start guide and usage

Getting started

Publishing, migrating and allowlisting your user model are covered under Install. Then:

1. To enforce modes and the kill switch, put the middleware on your own routes:

   // config/laranail/impersonator.php
   'routes' => ['auto_append_to_groups' => ['web']],

2. Check your setup:

   php artisan laranail::impersonator.doctor

Usage

use Impersonator;   // the auto-registered alias

Impersonator::enter($customer, mode: 'read_only', reason: 'Ticket #4182');
Impersonator::isImpersonating();     // true
Impersonator::leave();

The alias is registered by package discovery. If your application disables aliases, import the facade class itself instead:

use Simtabi\Laranail\Impersonator\Laravel\Facades\ImpersonatorFacade as Impersonator;

<x-laranail-impersonator::impersonate-button :user="$customer" />

{{-- once, in your layout --}}
<x-laranail-impersonator::banner />

Neither component needs a conditional: the button renders nothing when the operator may not impersonate that account, and the banner renders nothing when nobody is impersonating.

Every public name is vendor-scoped: laranail-impersonator.* routes, rate limiters, gate abilities and permissions, <x-laranail-impersonator::…> components. The bare names used before 0.1 (impersonator.leave, <x-impersonation-banner />, …) still work as deprecated aliases — see Architecture.

The two axes

The design decision that shapes everything else: how an impersonation is established and how the target is authenticated are independent, and the manager composes them.

	session adapter	sanctum	passport	jwt
session driver	the common case	—	—	—
token driver	cross-domain handoff	issue a token to a client	ditto	ditto
tenancy driver	per-tenant browser	per-tenant API	ditto	ditto

Collapsing these into one dimension is why most packages in this space cannot do the combinations. Keeping them apart makes "hand a mobile client a read-only token for this customer, expiring in ten minutes" a configuration rather than a fork.

Documentation

Thirty pages, in docs/ — they render on GitHub, so every link below works from here. The hosted copy at opensource.simtabi.com is the canonical home once this package is picked up by the docs aggregator.

Guides

• Installation — requirements, publishing, the one setting you must change
• Getting started — impersonate, scope, audit, in about five lines
• Configuration — every block, and what each one changes
• Architecture — the layers, the two axes, and why each choice was made
• Security model — what is guaranteed, how, and what is not promised
• Comparison — versus lab404, octopyid, stechstudio and stancl
• Release — versioning, what CI gates, the checklist

Reference

• Drivers — session, cross-domain token handoff, per-tenant
• Auth adapters — session, Sanctum, Passport, JWT
• Impersonation modes — the privilege boundary, and custom enforcers
• Authorization — policies, permissions, protected roles, hierarchy
• Impersonatable targets — multiple user models, each with its own guard
• The audit trail — two levels, causer, tamper evidence, export
• Remote revocation — the kill switch, and when it is immediate
• Break-glass approvals — four-eyes authorisation
• Blade components — five drop-ins that render nothing when unused
• Events — fifteen, including the refusals
• Notifications — target disclosure, security channel, approvals
• The REST API — eleven endpoints, off by default
• Console commands — doctor, enter, export, verify, prune

Recipes

• Add an impersonate button
• Restrict support staff to read-only
• Impersonate across domains
• Impersonate an API client
• Impersonate a second user model
• Add a custom mode
• Require approval for full access
• Extend a running impersonation
• Scope rows correctly under PostgreSQL RLS
• Kill an impersonation remotely
• Export for a compliance request
• Turn on and verify tamper evidence

Project

• OpenAPI specification — the REST contract, OpenAPI 3.1
• Changelog
• Contributing
• Security policy

Stability

Pre-1.0. The public surface — the facade, the Core contracts, the config keys, and the event classes — is what the test suite pins, and a breaking change to any of it will be called out in the changelog.

While pre-1.0 this repository keeps a single moving v0.1.0 tag per the laranail convention, so ^0.1 picks up changes on the next composer update.

Local development

composer install

vendor/bin/pest                          # add IMPERSONATOR_TEST_DB=pgsql|mysql for a real driver
vendor/bin/phpstan analyse               # level max, no baseline
vendor/bin/pint --test
vendor/bin/rector process --dry-run

Sanctum, Passport, JWT and stancl/tenancy are dev dependencies so their adapters are integration-tested against the real packages. CI additionally runs the suite with all four removed, which is what proves no hard dependency has crept in.

src/Core must import no Illuminate code; an architecture test enforces it.

Sister packages

Part of the laranail family of Laravel package tools.

Community

Questions and ideas belong in Discussions; bugs in Issues.

Contributing & security

See CONTRIBUTING.md. Report vulnerabilities privately to opensource@simtabi.com — see SECURITY.md, and never in a public issue.

License

MIT — see LICENSE. Copyright (c) 2026 Simtabi LLC.