Filament Saml2 Laravel Package

Getting Started

filament-saml2 3.0.0 is the Filament v5 line of the package. It is a feature-parity re-release of 2.0.0 (Filament v4) and 1.0.0 (Filament v3), so the main thing to verify first is your Filament major version.

composer require jeffersongoncalves/filament-saml2:"^3.0"

If you are on Filament v3 or v4, stay on ^1.0 or ^2.0 respectively — do not try to force 3.0 onto an older panel stack.

First steps:

1. Publish and review the package/underlying SAML config, then publish and run the migrations for the polymorphic saml2_identities table.
2. Configure at least one IdP tenant (entity ID, SSO URL, signing certificate, attribute mappings) in the SAML configuration provided by jeffersongoncalves/laravel-saml2.
3. Register the package's Filament plugin on the panel(s) that should offer SSO. The plugin adds the IdP login button to the Filament login page and wires the ACS/callback route.
4. Clear config cache and visit your panel login page; you should see one button per configured IdP tenant.

The first useful use case is a single panel with a single corporate IdP: user clicks the IdP button, authenticates at the IdP, is returned through the ACS endpoint, and is resolved/created locally by NameID or e-mail.

Where to look first:

• The published SAML config for tenant/IdP definitions.
• The package README for the exact plugin FQCN and panel registration snippet.
• The generated saml2_identities migration to understand the identity linkage model.
• The underlying jeffersongoncalves/laravel-saml2 config/docs for low-level SAML behaviour, since this package is the Filament integration layer.

Implementation Patterns

One plugin registration per panel. Register the plugin in each PanelProvider that should support SSO, and pass per-panel options there. This is the intended place for panel-specific behaviour such as which IdP tenants to show, button labels, and user-resolution settings. Keep panel options explicit rather than relying on a single global default.

Multiple IdPs via tenants. Model each identity provider as a tenant and let the package render one login button per tenant. Use distinct labels/icons so users know which button to pick. If local password login is not allowed, remove or hide Filament's default login form and rely on the IdP buttons.

RelayState-based panel resolution. A shared ACS endpoint uses RelayState to send the user back to the panel that initiated login. This is what makes multi-panel setups work without a separate callback per panel. Treat RelayState as part of your integration contract: do not rewrite or strip it in middleware, proxies, or custom login pages.

User resolution by NameID/e-mail. Prefer a stable NameID mapping where the IdP provides one; fall back to e-mail when that is the identifier you trust. Enable auto-create deliberately. For existing applications, resolve to existing users by e-mail and link the identity rather than creating a second account.

Polymorphic identities. The saml2_identities table is polymorphic, so the same package can link identities to different user models. This is useful if you have separate admin/customer models or guards per panel. Make sure the panel's auth guard and user provider match the model you expect the resolver to return.

Translations. The package ships en, pt_BR, and es. Publish/override the language files if you need different button text or error messages, and keep custom copy in your app's lang directory rather than editing vendor files.

Integration tips.

• Configure the IdP with the exact ACS URL for each environment (scheme, host, port, path).
• Use your IdP's metadata export to populate the tenant config, then verify the certificate and SSO URL.
• Test with a real IdP or a local SAML test provider before going live; SAML flows are difficult to validate from unit tests alone.
• Decide explicitly whether IdP-initiated SSO, SP-initiated SSO, or both are supported by your IdP and by your configuration.
• If you need custom user creation or attribute mapping, use the package's resolution extension points or the underlying laravel-saml2 events rather than branching the vendor code.

Gotchas and Tips

• Version matrix is strict. 3.0.x is Filament v5 only. Upgrading Filament majors means switching package majors; check composer why-not if installation fails.
• Config cache. After changing IdP tenants, certificates, or panel options, run php artisan config:clear (and optimize again in production). Stale cached SAML config is a common cause of "nothing changed".
• RelayState loss. Reverse proxies, load balancers, and custom middleware that rewrite query strings can break panel resolution. Confirm the ACS request arrives with RelayState intact and that your trusted proxies are configured.
• ACS URL mismatch. The ACS URL registered at the IdP must match the generated route exactly, including scheme and host. Local HTTP vs production HTTPS is a frequent failure.
• Auto-create and e-mail changes. If users are matched by e-mail and the IdP changes the e-mail, auto-create can produce duplicate accounts. Define a linking policy (NameID first, admin-approved re-link, etc.) before enabling auto-create broadly.
• Guard/provider mismatch. A SAML login can succeed at the IdP but fail to authenticate in Filament if the panel guard and user provider do not point at the model the resolver creates or returns.
• Identity uniqueness. Re-login should update or reuse the existing identity row. If you customize the identity model, preserve sensible uniqueness on the identity/tenant combination.
• Certificate rotation. IdP signing certificates expire. Update the configured x509 certificate and clear config cache; otherwise logins fail with signature validation errors.
• Session and cookie scope. Multi-panel or subdomain setups can lose the session if cookie domain/SameSite settings differ between the IdP return URL and the panel. Check config/session.php alongside SAML config.
• Logout is not always single logout. Logging out of Filament may not end the IdP session. If you need SLO, confirm it is configured and supported by the IdP; otherwise users may be silently signed back in.
• Debugging. Start with storage/logs/laravel.log, the underlying laravel-saml2 logging, and the SAML response/toolkit output. Temporarily increase SAML debug logging in non-production environments only.
• Do not edit vendor files. Publish config, migrations, and translations; use the package's options and extension points for custom resolution behaviour so future upgrades remain straightforward.
• No new features in 3.0.0. Treat this as a compatibility release. If you are migrating from 2.0.0, focus on Filament v5 compatibility and re-test the full login/RelayState/user-resolution path rather than looking for new configuration surface.