Filament Saml2 Laravel Package

Product Decisions This Supports

• Enterprise/B2B tier launch or gating. SAML 2.0 SSO is a recurring checkbox in enterprise procurement (Okta, Entra ID/Azure AD, OneLogin, Google Workspace). This package is the last-mile integration that turns "we support SSO" from a roadmap item into a shippable feature for Filament-based admin panels and internal tools.
• Build vs. buy for the SSO surface area. The hard, expensive part of SAML is the protocol layer (assertion validation, signature/certificate handling, clock skew, metadata exchange). That is delegated to the underlying laravel-saml2 library. What this package contributes is the Filament-specific glue: a login button, panel routing, and user provisioning. That is a small, well-bounded build — a reasonable "buy/borrow" call rather than a six-week protocol project.
• Multi-tenant / multi-IdP roadmap. "One login button per IdP tenant" plus RelayState-based panel resolution means a single Filament deployment can serve multiple customer orgs or internal business units, each with its own IdP, and land each user on the correct panel. This directly enables a multi-tenant commercial model without standing up separate app instances.
• Identity model decisions. The polymorphic saml2_identities table decouples external identities from your users table, which supports federated users, mixed local+SSO users, and a future "link multiple IdPs to one account" path. NameID / e-mail / auto-create resolution policies are product decisions (JIT provisioning vs. invite-only) that this package exposes as configuration rather than code.
• Per-panel policy. Different panels can enforce different IdP, provisioning, and option sets — supports segmenting e.g. a customer-facing portal from an internal ops console within one codebase.
• Filament major-version alignment. The 1.0/2.0/3.0 scheme maps one-to-one onto Filament v3/v4/v5. That makes the Filament v5 upgrade a predictable, low-ambiguity dependency bump rather than a feature-negotiation exercise — useful for roadmap planning around the framework upgrade cycle.
• Localization. Bundled en/pt_BR/es translations reduce friction for LatAm/European rollouts; additional locales are a cheap contribution.

When to Consider This Package

Adopt when:

• You are on Filament v5 and need SAML 2.0 SSO inside a panel — 3.0.0 is the only release line that targets v5.
• You need multiple IdPs or multiple panels with per-tenant login routing; the RelayState-based panel resolution is the differentiating capability here versus a generic SAML integration.
• You want JIT user provisioning with configurable NameID/e-mail/auto-create resolution and a clean identity-linking table, rather than hand-rolling user mapping.
• Your team is small and SAML protocol maintenance is not a good use of engineering time.
• You are comfortable depending on a single-maintainer, community-maintained package and can pin the version and absorb a fork if necessary.

Look elsewhere or build in-house when:

• You need OIDC / OAuth2 / social login rather than SAML — this package does not address that; Laravel Socialite plus a Filament plugin is the better fit.
• You require SCIM provisioning, IdP-initiated logout (SLO), or advanced attribute/role mapping — confirm coverage in the underlying laravel-saml2 library before committing; these are commonly outside the scope of thin wrappers.
• You need vendor support, SLAs, or a security review trail. A single-maintainer package with no prior assessment history should go through your own dependency and security review; budget for reading the underlying library's signature-validation code.
• You are on Filament v3/v4 — use 1.0.0/2.0.0 respectively; do not force a framework upgrade solely for this package, since 3.0.0 adds no features over its predecessors.
• You need fine-grained authorization (group/role-to-permission mapping from SAML attributes). Expect to build that layer yourself on top of the resolved user.

Assessment note on 3.0.0 specifically: this is a compatibility release, not a feature release — feature parity with 1.0.0 and 2.0.0 is explicitly stated. Migration risk is therefore concentrated in the Filament v4→v5 upgrade itself, not in this package. Pin ^3.0 and verify panel provider registration and the saml2_identities migration against your existing schema before rollout.

How to Pitch It (Stakeholders)

For executives: Enterprise buyers routinely require SAML-based single sign-on before they will sign. This package lets us deliver that on our Filament admin surfaces without a custom protocol build — it handles the IdP handshake, routes each customer's users to the right panel, and auto-provisions accounts on first login. It also supports multiple IdPs in one deployment, which means we can onboard several enterprise customers without standing up separate environments. Commercially, it converts an SSO checkbox from a multi-sprint project into a configuration exercise.

For engineering: A thin Filament adapter over jeffersongoncalves/laravel-saml2. We get a per-tenant login button, RelayState-based panel resolution, a polymorphic saml2_identities table, per-panel options, and en/pt_BR/es translations. Version 3.0.0 is the Filament v5 line and is feature-identical to the v3 and v4 lines, so this is a dependency-alignment bump — no new behavior to regression-test beyond the framework upgrade. It is a single-maintainer community package, so: pin the version, run our standard dependency and security review, and confirm the underlying library's signature-validation and certificate-rotation handling before we depend on it for production auth. If we need SCIM, single logout, or group-to-role mapping, plan to build those ourselves or evaluate a commercial IdP integration instead.