Download the PHP package serenity_technologies/admin-dashboard-guard without Composer

admin-dashboard-guard

A Laravel package that places a two-factor passphrase + password authentication wall in front of any admin-restricted page — Horizon, Telescope, Pulse, Filament, or any custom route — with zero extra database tables.

How It Works

Access to a protected page requires two sequential steps:

1. Passphrase step — The admin provides a short-lived secret passphrase (bcrypt-hashed in the database). On success, a 10-minute session window opens.
2. Password step — Within that window, the admin enters their account password to receive a fully-authenticated session (valid for 60 minutes by default).

Each protected page runs its own independent session, so authenticating to /horizon does not grant access to /telescope.

Generating a passphrase via Artisan emails it directly to the admin and schedules automatic revocation after a configurable delay.

Requirements

Sanctum is only needed if you want to accept a bearer-token as an alternative to the session flow. It is listed under suggest in composer.json and is not required by default.

Installation

1. Require the package

The service provider is auto-discovered via extra.laravel.providers in composer.json.

2. Publish the config

This creates config/admin-dashboard-guard.php.

3. Add the passphrase column to your admin model

Run the migration:

4. Configure your admin model

Set the model in .env:

Your model must implement Illuminate\Contracts\Auth\Authenticatable and have both a passphrase column (nullable, stores a bcrypt hash) and a password column.

5. Configure the auth guard

Ensure an admin guard is defined in config/auth.php:

Then set in .env:

Protecting a Page

The package registers a named middleware alias for every entry in protected_pages. The alias format is admin.{key}.

Horizon

In config/horizon.php:

Telescope

In app/Providers/TelescopeServiceProvider.php:

And add the middleware to the route group in your telescope service provider or routes/web.php:

Any Custom Route

You can protect any route or route group with the admin.{key} alias, where key matches an entry in protected_pages:

Adding a New Protected Page

Open config/admin-dashboard-guard.php and add an entry to protected_pages:

The package automatically:

• Registers an admin.pulse middleware alias
• Defines a viewPulse gate (or skips it if gate is null)
• Registers GET /pulse/password and POST /pulse/password routes for the password step

protected_pages Options

Stealth Mode

When stealth mode is enabled the auth wall is completely invisible to unauthenticated requests. The passphrase form is never shown — every bare access attempt returns a plain 404 Not Found, exactly as if the route did not exist.

The only way in is to carry the passphrase directly in the URL query string:

A valid passphrase silently redirects to the password step as normal. A wrong passphrase also returns 404 (not 401), so nothing about the auth wall is revealed.

Enable globally (all protected pages)

Or directly in the published config:

Enable per page (overrides the global default)

Tip: Combine stealth mode with a short --delay when generating passphrases so the URL is valid only for a small window of time.

Artisan Commands

All commands are prefixed with admin-guard: to avoid collisions with the host application.

Generate a passphrase for one admin

Generates a random passphrase, bcrypt-hashes and saves it to the admin record, emails it to the admin, then queues an auto-removal job after --delay hours.

Example output:

Generate passphrases for all admins

Runs the single-admin flow for every record returned by the configured model. Accepts the same --bcc, --length, and --delay options.

Remove a passphrase for one admin

Immediately nulls out the passphrase column for the given admin, invalidating any active passphrase-step session.

Clear passphrases for all admins

Nulls the passphrase column for every admin that currently has one set. Prompts for confirmation unless --force is passed.

Incident response tip: Run admin-guard:clear-passphrases --force to instantly revoke all active passphrases if you suspect a passphrase has been compromised.

Configuration Reference

Environment Variables

Customising the Views

Publish the Blade views to override them:

Files land in resources/views/vendor/admin-dashboard-guard/:

Each view receives $toolName, $toolPath, and $themeColor variables.

Customising the Passphrase Email Subject

Pass a custom subject when constructing the mailable directly:

Sanctum Bearer Token Fallback

When sanctum_support is true and laravel/sanctum is installed, the middleware also accepts a valid personal-access token belonging to an instance of the configured model class. This lets programmatic/API clients access protected pages without going through the browser-based session flow.

Custom Authorization Conditions

You can define additional custom conditions to authorize an admin before allowing dashboard access. This is useful for checking user roles, statuses, or other custom criteria.

1. Global or Per-Page Config Condition Class

Create an invokable/callable class that receives the admin model, the HTTP request, and the tool name:

Then register it globally in config/admin-dashboard-guard.php:

Or configure it per-page inside the protected_pages array:

2. Runtime Callback (Closure)

Alternatively, register a closure check dynamically in your AppServiceProvider (or any service provider) using the static checkUsing method:

Security Notes

• Passphrases are never stored in plain text — only a bcrypt hash is saved in the database.
• Each passphrase hash is verified with Hash::check() by iterating admin records; no plain-text comparison occurs.
• The passphrase step has a configurable short TTL (10 minutes by default) and is cleared from the session once the password step completes.
• The fully-authenticated session is TTL-scoped per protected page, so sessions for /horizon and /telescope are completely independent.
• Use admin-guard:clear-passphrases --force to invalidate all active passphrases immediately during a security incident.
• The auto-removal delay (--delay) is enforced via a queued job so that passphrases can never be left active indefinitely by accident.

License

MIT