Filament Access Secret Laravel Package

Getting Started

This package adds a URL-based access secret (typically a query string or path segment) to your Filament panel so that only visitors who know the secret can reach /admin. It's aimed at small deployments and staging environments where you want a quick "password in the URL" without building full auth.

Minimal setup:

1. Install the package:

   composer require dasundev/filament-access-secret
   

2. Publish and set the secret. Most versions read either an env variable (e.g. FILAMENT_ACCESS_SECRET) or a config value. Check config/filament-access-secret.php if one was published, otherwise look at the package README for the expected env key name — this is the single most likely break point on first install.
3. Register the middleware on your panel provider (app/Providers/Filament/AdminPanelProvider.php). The plugin ships a middleware you attach to the panel, typically via ->middleware([...]) or a ->authMiddleware([...]) call. Confirm which one the package targets in your Filament major version (middleware vs authMiddleware behave differently).
4. Clear caches: php artisan config:clear && php artisan optimize:clear.
5. Visit https://yourapp.test/admin?key=YOUR_SECRET (the parameter name is usually configurable — check the config). If it works, a session/cookie is set so subsequent /admin visits inside the same session don't need the query string again.

First use case: guard a staging admin panel behind a shared secret that you can rotate per environment, while keeping the real production panel on normal Filament auth.

Implementation Patterns

Per-environment secrets. Give each environment its own secret via .env (FILAMENT_ACCESS_SECRET=staging-abc123) so leaked staging secrets can't unlock production. Combine with .env.example placeholders like change-me so new checkouts don't accidentally ship a valid secret.

Panel-scoped middleware (multi-tenant / multi-panel setups). Register the middleware only on the panel you want protected. If you have PatientPanelProvider and AdminPanelProvider, put the secret middleware on AdminPanelProvider only — don't add it globally in bootstrap/app.php, or you'll lock out Livewire asset endpoints that don't share your browser session.

Rotating secrets without logging out everyone. Because most implementations store authorization in the session/cookie, rotating the secret doesn't invalidate existing sessions until they expire. If you need immediate revocation, either reduce session lifetime or add a version/epoch to the session key (e.g. include the secret hash in the session value rather than a boolean flag).

CI/CD integration. In pipelines, set the secret as a protected environment variable (GitHub Actions secret, Vault, etc.) and never commit it. On deploy, pass it through php artisan config:cache-friendly env, since the config cache embeds the value at build time — meaning every environment that shares a config cache artifact needs the same secret unless you rebuild per environment.

Combine with IP allowlisting. Treat this as a first gate, not the only gate. Pair it with ->middleware(['throttle:admin', RestrictToIps::class, ...]) so that a leaked secret still requires a known client IP. This is a cheap upgrade that massively reduces blast radius.

Session-bound flow for UX. If you're showing the secret to non-technical stakeholders, link them to the URL once (/admin?key=xyz), let the session cookie do the rest, and document that clearing cookies means re-entering the URL. Avoid telling them to bookmark the URL — bookmarks leak the secret into browser sync services.

Testing. In Pest/PHPUnit, the secret must be set in the test environment config for feature tests that hit the panel. Add a helper like actingWithAccessSecret() that appends ?key=... to test calls, or bypass the middleware in tests via ->withoutMiddleware(SecretMiddleware::class) to keep unrelated tests fast.

Gotchas and Tips

Secrets in URLs are logged everywhere. Query-string secrets appear in web server access logs (nginx/apache $request_uri), reverse-proxy logs (Cloudflare, ALB), browser history, and Referer headers sent to third-party assets. Prefer using this package only behind VPN/IP allowlisting, and force HTTPS so the URL isn't sniffable in transit. If your threat model tolerates none of that, this package isn't the right tool — use Filament's built-in auth.

Middleware order matters. Filament assembles its own middleware stack. If you add the secret middleware too early (before StartSession), the package can't persist "already authorized" state and every request demands the key in the query string. Add it after Filament's session middleware so the session shortcut works. If you see the key required on every single navigation, this is almost certainly the bug.

Livewire and asset URLs. Filament's UI makes background Livewire requests to /livewire/... and loads assets from /admin/css/.... These routes typically bypass your panel's middleware stack (they're not panel routes), so they generally work fine — but if you ever wrap the middleware in a global guard, expect broken CSS, failed file uploads, and 419 errors. Keep it panel-scoped.

Config cache trap. php artisan config:cache freezes env values into bootstrap/cache/config.php. If your deploy runs config:cache in a Docker build stage shared across environments, every environment inherits the build-time secret. Either build per environment or read the secret from env() at request time (not config) — though that's an anti-pattern Filament apps should avoid; rebuilding per env is the cleaner fix.

Secret rotation isn't immediate. Sessions already validated won't be re-checked until they expire (typically SESSION_LIFETIME = 120 minutes). During an incident, rotate the secret and flush the relevant session store (php artisan session:clear or delete the session driver's keys) rather than assuming the new secret takes effect instantly.

Empty or missing secret behavior is usually permissive or fatal — check yours. Most implementations treat a missing config value as "middleware disabled" (so the panel is wide open) or "middleware always denies" (so you lock yourself out). Verify which by removing the env locally and hitting /admin. Set a fail-closed expectation explicitly in your deployment checklist.

Debugging "locked out of my own admin." Checklist in order: (1) is the env var actually present in config:cache? (php artisan tinker → config('filament-access-secret.secret') or whatever key the package uses). (2) Is the middleware registered on the right panel provider? (3) Are you hitting a route that actually runs the panel middleware (not a Filament auth route or a cached asset)? (4) Does the query-string parameter name match the config exactly (case-sensitive)?

Extension points. If you need custom logic (e.g. allow a second secret for support staff, or log every failed access to an audit table), the middleware is usually a single small class — php artisan vendor:publish --tag=filament-access-secret (tag name may vary) will copy it into app/Http/Middleware/, letting you subclass and add logging, timing checks, or geo-blocking without forking the package.

Low-maturity package signal. At 38 stars with a recent release, expect small API churn between minors and sparse documentation around edge cases like Livewire file uploads or Filament's auth-redirect flow. Pin to a specific version in composer.json ("dasundev/filament-access-secret": "1.x" rather than "^1.0") until you've validated behavior against your Filament major version, and read the middleware source once — it's short and the behavior is more authoritative than the README.