imanghafoori/laravel-masterpass
Laravel MasterPass lets you log in as any user by entering a single master password instead of the real one, making it easy to test and debug your app without resetting credentials.
MasterPass is a support/debugging tool, not application logic. It lets you authenticate as any user through the normal login form by supplying a single shared "master password" alongside that user's email/username — no password reset emails, no database edits, no tinker session. Day-to-day, you reach for it when reproducing a bug that only reproduces with a specific user's data, or when a customer reports something and you need to see exactly what they see.
Minimal steps:
composer require imanghafoori/laravel-masterpass
php artisan vendor:publish --provider="Imanghafoori\MasterPass\MasterPassServiceProvider"
Then set the secret in .env (never commit it):
MASTER_PASSWORD=some-long-random-string
Since Laravel 5.5 the service provider is auto-discovered, so there is nothing to register in config/app.php. Confirm the published file exists at config/masterpass.php and that it reads from env('MASTER_PASSWORD').
Where to look first:
config/masterpass.php — that is the whole configuration surface; read it before assuming behaviour.vendor/imanghafoori/laravel-masterpass/src/ — the package is small enough to read end-to-end in ten minutes. Check which guard/provider it hooks into (it typically registers a custom user provider or an Attempting listener), because that determines whether it works with your guard at all.config/auth.php — confirm your web guard uses the provider you think it does.First use case: in staging, log in as the affected user with their email and the master password, reproduce the bug, then log out. Nothing is mutated, no password is reset, the user is never notified.
Environment-scoped secret. Treat the master password as a production credential even if you only intend to use it locally. Generate it per environment (Str::random(48)), store it in your secret manager, and never reuse it across staging and production. A .env.example entry with an empty value is fine; a value is not.
Never leave it unguarded in production. If you enable it on prod at all, put your own gate in front of it. The cleanest place is a listener or middleware that refuses the attempt unless the current context is authorized:
// app/Providers/AuthServiceProvider.php
Gate::define('use-masterpass', fn ($user) => $user?->is_support_staff ?? false);
and short-circuit the attempt when the environment is wrong:
Event::listen(\Illuminate\Auth\Events\Attempting::class, function ($event) {
$isMaster = ($event->credentials['password'] ?? null) === config('masterpass.master_password');
if ($isMaster && ! app()->environment(['local', 'staging'])) {
abort(403);
}
});
The exact hook depends on how the package intercepts authentication — verify against the source, then layer your guard on top rather than forking the package.
Audit every use. Impersonation is the kind of thing that should appear in logs before anyone asks. Listen for Illuminate\Auth\Events\Login and write an impersonations row: actor (from a session key you set when you started), target user id, IP, user agent, timestamp. A ten-line listener here pays for itself the first time an auditor asks "who accessed this account."
Admin-initiated impersonation. The pattern that scales best is not "type the master password into the login form" but an admin-only route that uses Laravel's built-in Auth::loginUsingId():
Route::post('/impersonate/{user}', function (User $user) {
Gate::authorize('impersonate', $user); // admin-only policy
session(['impersonator_id' => auth()->id()]);
Auth::login($user);
return redirect('/dashboard');
})->middleware(['auth', 'can:impersonate'])->name('impersonate');
Route::post('/impersonate/stop', function () {
$original = User::findOrFail(session()->pull('impersonator_id'));
Auth::login($original);
return redirect('/admin');
})->middleware('auth');
Use MasterPass for the case where you have no admin UI (or you're on a read-only prod shell) and the route approach for everything else. The two complement each other: MasterPass is the break-glass path, the route is the repeatable one.
Testing. Do not use MasterPass in your test suite. $this->actingAs($user) in feature tests and Auth::loginUsingId() in Dusk give you the same outcome without shipping a universal key into CI.
Login events since the last rotation..env copied to production with MASTER_PASSWORD=master or the package default still in place. Add a boot-time check that throws if the value is set and shorter than ~32 characters, or if APP_ENV=production and the value is non-null and un-audited.Auth::provider(), the package may only hook the default web guard/session flow. Test with your actual login endpoint before relying on it. API token guards are out of scope entirely.MASTER_PASSWORD in .env, run php artisan config:clear (or config:cache again). A stale cached config is the usual reason "it just stopped working."throttle middleware wraps your login route. A bot hammering your login form can lock you out of the break-glass path. Consider excluding the master-password path from throttling, or keep a second access route.Auth::logout() and, if you use remember tokens, clear the cookie — otherwise a stale remember_web_* token can silently re-authenticate the impersonated user on a shared machine. Session::invalidate() plus Cookie::forget() is the safe combination.Hash::check, so a value that happens to equal another user's real password is fine — but don't reuse your own account password for it "for convenience."composer.json constraint against your Laravel version (11/12 support) and read the source before upgrading majors; you are effectively your own maintainer.vendor/.How can I help you explore Laravel packages today?