Download the PHP package eloquent-works/masquerade without Composer

🎭 Laravel Masquerade

A feature-rich user impersonation package for Laravel.

Laravel Masquerade lets trusted administrators, support agents, and staff safely sign in as another user while preserving the original account, enforcing permission checks, blocking sensitive actions, limiting impersonation duration, and recording a full audit trail.

✨ Highlights

• Secure session-backed user impersonation
• Original user restoration after masquerade sessions
• Configurable auth guard support
• Configurable user model for built-in routes
• Optional built-in start and stop routes
• Controller-driven impersonation flow
• Model-level permission methods
• Protection against nested impersonation
• Protection against impersonating yourself
• Optional required reason before starting a session
• Session ID regeneration when starting and stopping
• Configurable max session duration
• Session extension with optional max-duration caps
• Automatic expiration middleware
• Sensitive-route blocking middleware
• Middleware for routes that require an active masquerade session
• Request context middleware for support panels and toolbars
• Full audit logging with actor and target morph relationships
• Reason, IP address, user agent, metadata, start time, and end time logging
• Query scopes for action, UUID, impersonator, and target log filtering
• Optional denied-attempt logging
• Start, stop, denied, expired, and extended events
• Blade conditional directive and banner directive
• Publishable banner view
• Facade and global helper
• Install and log pruning Artisan commands
• Configurable table name, messages, redirects, and routes
• Laravel Pint, PHPStan/Larastan, PHPUnit, Testbench, and GitHub Actions setup

📋 Requirements

📦 Installation

The install command publishes the configuration file, migration, and banner view.

Publish only the configuration file:

Publish only the migration:

Publish only the banner view:

Force republishing package assets:

👤 Prepare Your User Model

Add HasMasquerade to the account model that can perform or receive impersonation.

By default, canMasquerade() returns false. This means nobody can masquerade until your application explicitly allows it.

🎭 Start Masquerading

You may also provide a specific impersonator and guard:

🛑 Stop Masquerading

When stopped, Masquerade logs the original user back in and clears the masquerade session state.

🔎 Inspect the Current Session

Update safe session metadata while troubleshooting:

Extend the active session when a support task legitimately needs more time:

The helper returns the same manager instance:

🛡️ Protect Routes

Block sensitive actions while masquerading:

Enforce automatic expiration on normal authenticated routes:

Require an active masquerade session:

Share masquerade context on the request for toolbars, macros, and support panels:

🧭 Built-In Routes

When routes are enabled, Masquerade registers:

Start from a Blade form:

Stop from a Blade form:

Disable built-in routes if you want to provide your own controller flow:

🪪 Permissions

Masquerade checks both sides of the impersonation request.

You may disable model permission methods in the config if your application handles authorization elsewhere:

🧾 Audit Logs

Every started, ended, and expired masquerade session can be recorded in masquerade_logs.

Each log may include:

• Masquerade UUID
• Action: started, ended, denied, expired, or extended
• Guard name
• Impersonator morph type and ID
• Target morph type and ID
• Reason
• IP address
• User agent
• Metadata
• Started timestamp
• Ended timestamp

Access the actor and target models:

Filter logs with expressive scopes:

⏱️ Duration Limits

Masquerade can automatically expire old sessions.

Add the duration middleware to routes that should enforce the limit:

You can also check expiration manually:

🚫 Sensitive Route Blocking

Use masquerade.block on routes that should never be available while impersonating another account.

Good examples include:

• Billing changes
• Password changes
• Two-factor authentication changes
• Email address changes
• API token creation
• Account deletion
• Admin permission changes

🧩 Blade Directives

Show UI only while masquerading:

Render the included banner:

Or include the published view manually:

📡 Events

Masquerade dispatches events you can listen for:

Example listener registration:

⚙️ Configuration

Publish the configuration file:

Important options:

🧰 Commands

Examples:

🧪 Testing Your App Integration

A simple feature test might look like this:

📝 Session Notes

🎟️ Ticket Context

🛡️ Ability Blocking

Block sensitive actions while masquerading:

Or use middleware:

📤 Audit Export

🚨 Risk Detection

Enable risk detection in config:

Risk detections are logged with:

📚 Documentation

Full documentation is available in the docs directory:

• Installation
• Configuration
• Architecture
• Masquerading
• Permissions
• Routes
• Middleware
• Advanced Features
• Audit Logs
• Views and Blade
• Events
• Commands and Scheduling
• Customization
• Security
• Testing

✅ Quality Checks

Or run the tools separately:

🔐 Security

Only allow highly trusted users to masquerade. Always require authorization before starting a session, consider requiring a reason, and block sensitive account, billing, authentication, and destructive routes with masquerade.block.

Masquerade regenerates the session ID when starting and stopping by default. Keep that enabled unless your application has a specific reason to disable it.

🤝 Contributing

See CODE_OF_CONDUCT.md.

🙏 Credits

Built by Eloquent Works.

📄 License

Laravel Masquerade is open-source software licensed under the MIT License.