README

Controlled and audited user impersonation plugin for Laravel and Filament applications.

Allows an authorized operator to temporarily authenticate as another user while preserving a mandatory audit trail of the real operator.

Requirements

PHP >= 8.2
Laravel >= 12
Filament >= 5
spatie/laravel-activitylog
spatie/laravel-permission (optional — required only for role/permission-based authorization)

Installation

composer require chuimi/filament-impersonation

Publish the configuration file:

php artisan vendor:publish --tag=filament-impersonation-config

Minimal setup

Installing the package alone is not enough for the impersonation action to appear in the UI. The plugin must be registered in a panel and the action must be added to a resource explicitly.

The package does not auto-register in any Filament panel or inject the action into any resource. This is intentional — applications may have multiple panels and different authorization policies per context.

1. Install and publish config

composer require chuimi/filament-impersonation:^0.1.1
php artisan vendor:publish --tag=filament-impersonation-config

2. Set required configuration

In config/filament-impersonation.php, configure at minimum guard, user_model, an authorization rule (operator_roles or can_impersonate), and protected_roles.

3. Register the plugin in your panel — required for the banner

use Chuimi\FilamentImpersonation\Filament\ImpersonationPlugin;

->plugins([ImpersonationPlugin::make()])

4. Add the action to the users table — required for the trigger

use Chuimi\FilamentImpersonation\Filament\Actions\ImpersonateAction;

->actions([ImpersonateAction::make()])

5. Clear caches

php artisan optimize:clear

For a detailed checklist including config examples, redirects, and manual verification steps see Integration guide — Minimal setup checklist.

Usage

Register the plugin in a Filament panel

use Chuimi\FilamentImpersonation\Filament\ImpersonationPlugin;

$panel->plugin(ImpersonationPlugin::make());

Once registered, the impersonation banner is shown automatically at the bottom of the panel while any impersonation session is active.

Add the action to a resource or page

use Chuimi\FilamentImpersonation\Filament\Actions\ImpersonateAction;

->actions([
    ImpersonateAction::make(),
])

The action is hidden automatically when the current user cannot impersonate the record. It must be added manually to the resources or pages where impersonation should be available.

Enrich activity logs with impersonation context (opt-in)

Apply the trait to any Eloquent model that uses spatie/laravel-activitylog and should include impersonation context in its activity entries:

use Chuimi\FilamentImpersonation\Concerns\HasImpersonationActivityContext;
use Spatie\Activitylog\Traits\LogsActivity;

class SomeAuditableModel extends Model
{
    use LogsActivity;
    use HasImpersonationActivityContext;
}

This trait is opt-in and must be added manually per model. The package does not apply impersonation context globally to all activity logs.

Security notes

impersonation.started is mandatory and recorded before the user switch. If it cannot be written, impersonation does not start.
Manual logout during impersonation does not restore the original operator.
The stop route uses POST with CSRF protection via the web middleware stack. The banner renders the CSRF token automatically.

Full details in docs/SECURITY.md.

Documentation

Document	Description
Integration guide	Installation, plugin registration, authorization, redirects, audit trait, multi-guard
Security guide	Security model, audit events, CSRF, known risks, design decisions, audit queries for administrators
Architecture	Design decisions, session payload, activity log events, internal flow
Architecture map	Component overview and sequence diagrams

License

MIT — see LICENSE.

chuimi / filament-impersonation

Maintainers

Package info

Statistics

Security