Filament Sso Client Laravel Package

Getting Started

• Install the package alongside its underlying client:

  composer require jeffersongoncalves/filament-sso-client
  

  Confirm jeffersongoncalves/laravel-sso-client resolves to ^1.1 — this release depends on it and will not work with the 1.0 line of that package.
• Publish and review config before touching a panel:

  php artisan vendor:publish --tag="filament-sso-client-config"
  

  Expect the IdP settings (metadata/authorize/logout endpoints, client ID, client secret), the ACS/callback route, and the login-mode switch to live here — the panel-facing package is mostly a thin Filament layer over the client config, so most "why isn't this working" answers are in this file, not in Filament.
• Register the plugin on the panel, not globally:

  public function panel(Panel $panel): Panel
  {
      return $panel
          ->plugin(SsoClientPlugin::make());
  }
  

• First use case: keep the normal Filament login form and simply add the SSO button, verify one round trip (login → IdP → ACS → panel), then tighten to SSO-only or forced redirect once the callback URL and IdP allow-list are confirmed working in the target environment.
• Check the client's own README for the non-Filament pieces (route registration, user provisioning/first-login behaviour, auth guard wiring). This package does not replace that setup; it consumes it.

Implementation Patterns

• Two-panel split. Run SSO-only on the staff panel and leave the default Filament login on an internal/break-glass panel. Filament v3 panels are independent, so a misconfigured IdP takes down one panel rather than every login surface.
• Progressive rollout. Ship with button-only mode, watch the IdP logs for a release cycle, then flip to SSO-only or forced redirect. Forced redirect is the setting most likely to strand users mid-incident, so treat it as a separate deploy.
• Local and CI bypass. Gate the plugin registration by environment (->plugin(...) only outside local) or point the config at a stub IdP. Because forced redirect intercepts the panel login route, a developer without IdP access will otherwise be locked out of their own app — add this guard on day one, not after the first complaint.
• Federated logout expectations. The user-menu logout item ends the IdP session as well as the local one. If a tenant has other SPs behind the same IdP, logging out of Filament logs them out of everything — surface this in release notes for users, because it is a behaviour change from stock Filament.
• SLO enforcement is a per-request check. Treat it as middleware-class behaviour on panel requests: fine for typical panels, but measure it on high-traffic ones. Pair it with a short cache of the IdP session validity if the check is a network call, or you have added an external dependency to every panel page load.
• Authorisation still belongs to you. SSO answers "who is this"; it does not answer "may they see this panel". Keep canAccessPanel() / FilamentUser implementations and role provisioning intact, and assert them in tests — the SSO path bypasses the password form, and it's easy to assume it also bypasses your gate.
• Testing. Fake the client's HTTP calls and drive the ACS route directly with a signed assertion fixture; assert panel access for a provisioned user and denial for a deactivated one. Cover the logout path too — assert both the local session and the IdP end-session redirect.
• Callback URL is the integration contract. Pin the ACS route per environment and give the IdP the exact URL, including scheme, APP_URL host, and any locale/prefix segment Filament adds to panel paths.

Gotchas and Tips

• Lockout risk is the headline pitfall. SSO-only or forced redirect plus a wrong client secret equals no way in. Keep an artisan-created user or a second panel available, and know the config key to disable the plugin before you deploy it.
• Redirect loops. Forced redirect on a panel whose login route also matches the enforcement middleware will bounce until the browser gives up. If you see this, check route exclusions in the published config and confirm the ACS route sits outside the panel's auth middleware.
• SLO failures look like random logouts. A session invalidated at the IdP but still alive locally (or vice versa) produces intermittent 302s to login. Log the IdP's SLO response and the local session ID together when debugging; without that correlation this is guesswork.
• Session/domain quirks. If the app and IdP are on different domains, SameSite cookie settings and HTTPS-only secure cookies matter for the post-login redirect to carry state. Test in the real domain topology, not just localhost.
• Config cache. php artisan config:cache during deploy is the usual reason a changed client ID "didn't take". Clear and rebuild in the deploy script, and keep secrets in env, not in the published file.
• Multiple panels, one config. Verify whether login-mode and enforcement settings are read per panel or globally. If they're global, per-panel SSO-only is not achievable without separate config loads — worth confirming before designing around it.
• Upstream pinning. You inherit laravel-sso-client's behaviour and bug surface. Pin the minor version and read its changelog on every bump; a patch there can change logout or provisioning semantics without any change in this package.
• Extension points are the login page class, the user-menu items, and the plugin's config array. Override the login page in your own panel rather than editing vendor files, and keep customisations thin — this is a 1.0.0 and the public surface will move.