Laravel Filament Sso Laravel Package

Getting Started

1. Install both packages. The plugin is a thin Filament layer over the SSO client, so you need the client first:

   composer require postiefs/laravel-sso:^1.0 postiefs/laravel-filament-sso
   

   Pin postiefs/laravel-sso to ^1.0 — the plugin’s major version tracks it.

2. Configure the portal credentials in the postiefs/laravel-sso config (client ID/secret, portal URL, callback route). Nothing in the Filament plugin replaces this; if the SSO client isn’t configured, the button will render but the round trip will fail.

3. Register the plugin on the panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(SsoPlugin::make())
           // ...
   }
   

4. Look first at the docs/ folder in the package rather than the source — the plugin is small, and the docs describe the two behaviour switches (redirectLogin(), allowLocalLogin()) that determine almost everything about how your login page behaves.

5. First use case: load /admin/login and confirm the “Sign in with Microsoft 365” button appears below the standard form. Click it, complete the portal flow, and verify you land back on the panel dashboard. That single pass exercises the button, the callback, the session rules and the browser guard.

Implementation Patterns

Panel provider is the whole integration surface. SsoPlugin::make() is the only entry point — there is no service provider to publish, no middleware to register by hand. Keep all SSO-related panel configuration in the panel provider so it is visible next to the panel it affects.

Decide your login posture explicitly. The default behaviour (button below the form) is the softest rollout: existing local users keep working while you pilot SSO. Once you are confident:

->plugin(
    SsoPlugin::make()
        ->redirectLogin()      // everyone goes to the portal
        ->allowLocalLogin()    // but ?local=1 still reaches the local form
)

Treat this as a deliberate two-step migration. redirectLogin() without allowLocalLogin() is a hard cutover with no break-glass path — only do that once the portal’s uptime is something you trust.

Use ?local=1 as a documented break-glass route, not a secret. When the portal is down, /admin/login?local=1 is the way in. Put it in your runbook and your on-call notes. Because it is a query string it is trivially discoverable, so pair it with whatever other controls you have (IP allow-list at the edge, an App::isProduction() guard, or disabled local accounts).

Authorisation stays yours. The portal authenticates; it does not authorise. The portal’s roles are never applied to users, so map your own roles (Spatie, or otherwise) after the user is resolved — typically in a listener on the SSO login event, or a small User resolution hook. New portal users arriving without roles should land in the safest default role, not an admin one.

Multi-panel apps: the callback returns to the default panel, not the panel the user started from. If you run separate admin/app panels, either accept that everyone funnels through the default panel first, or gate your panels so the redirect is harmless. Do not assume the plugin will round-trip a user to /app because they clicked the button on /app/login.

Local logins keep their old behaviour. Only portal sessions redirect to the launchpad on sign-out; local logins sign out as before. If your tests assert on logout redirects, split them into portal and local cases rather than changing one expectation.

Gotchas and Tips

• The session rules and browser guard run on every panel request, Livewire updates included. This is the most likely source of surprises. A long-lived page with a stale portal session can be bounced to the portal mid-interaction — a Livewire action may return a redirect rather than the JSON your component expects. Test your heaviest Livewire screens (tables with polling, modals, file uploads) after enabling the plugin, and make sure your JS handles a redirect response gracefully rather than logging a console error and leaving a spinner.
• The guard applies to every page, so error pages and anything outside the panel are unaffected — but assets, health checks and webhook routes must not be inside the panel’s middleware stack. If you see redirect loops after install, check that your panel’s auth/session middleware has not been duplicated or reordered.
• Debugging login loops: a loop almost always means the callback session isn’t persisting (session domain, SESSION_DOMAIN, or a proxy terminating TLS and confusing cookie Secure/SameSite). Clear config cache (php artisan config:clear, optimize:clear) before chasing it further — a cached panel config is a common culprit after toggling redirectLogin().
• allowLocalLogin() is a switch, not a form. It keeps the local form reachable; it does not create users or reset passwords. Make sure at least one local account with a real password exists before you turn on redirectLogin(), or you will lock yourself out of your own panel.
• Don’t assume portal role names mean anything in your app. Because portal roles are discarded, an “Admin” on the portal is a plain user in Laravel until you map it. Write that mapping down; a silent gap here is the most dangerous failure mode of the package.
• Extension points: the button is rendered as part of the login page, so restyle it with a panel render hook / custom theme rather than editing vendor views. Anything deeper (custom user provisioning, extra claims) belongs in postiefs/laravel-sso events, not in the Filament plugin.
• Version matrix is wide (Filament 3/4/5, Laravel 11/12/13). Upgrade Filament and Laravel in separate steps from this package, and re-check the login page after each — a Filament major bump can change the login page’s render hooks without the plugin version changing.