Filament Saml2 Laravel Package

Technical Evaluation

What this release is

• filament-saml2 3.0.0 is the first release of the package targeting Filament v5. It is explicitly feature-parity with 1.0.0 (Filament v3) and 2.0.0 (Filament v4).
• Practically, this is a compatibility release, not a capability release: no new features, no stated security fixes, no deprecations. The value is that teams standardising on Filament v5 can now adopt SAML SSO without pinning an older Filament major.
• It is a thin Filament-facing layer over jeffersongoncalves/laravel-saml2, which does the actual SAML SP work. We are therefore adopting two packages, one of which is a single-maintainer dependency chain.

Architecture fit

• Fits the standard Laravel/Filament service-provider + panel-provider model. Integration surface is small: a login button per IdP tenant, a saml2_identities polymorphic table, panel-level options, and config-driven IdP metadata.
• The RelayState-based panel resolution is the architecturally interesting piece for us: one SP endpoint can serve multiple Filament panels, which suits a multi-panel admin/staff/customer-portal layout. It also means RelayState becomes a security-relevant input — it must be validated against an allow-list of known panels, not used as a free redirect target.
• Polymorphic saml2_identities is the right model: it lets users be attached to different authenticatable models (e.g. User, Admin, Partner) without schema divergence. It also means identity linkage is a first-class data concern we must own — this is our data, not the vendor's.
• Per-panel options support a mixed estate (some panels SSO-only, some local-auth fallback), which de-risks incremental rollout.

Integration feasibility

• Low code footprint, Composer-installable, no infrastructure to run. If we are already on Laravel + Filament v5, this is days of work, not weeks — dominated by IdP-side configuration and UAT, not by application code.
• Multi-tenant IdP support (one button per IdP tenant) is a genuine fit for B2B customers who each bring their own IdP; that is often a contractual requirement, not a nice-to-have.
• Auto-create/JIT provisioning plus NameID/e-mail resolution removes manual onboarding, but that is exactly where the risk concentrates (see below).

Technical risk

• Semver is coupled to Filament, not to this package's API. Majors 1/2/3 map to Filament 3/4/5, not to breaking API changes here. Consequence: a "major" bump is often functionally trivial (as this one appears to be) — but it also means our upgrade cadence is chained to Filament's, and we must upgrade both in lockstep. Plan for that.
• Bus factor / supply chain. Two packages, apparently one maintainer, published to Packagist. SSO sits directly on the authentication path — the highest-blast-radius code in the application. A single-maintainer dependency here is a real (if manageable) risk.
• SAML correctness is easy to get subtly wrong: assertion signature validation, audience/recipient restriction, NotBefore/NotOnOrAfter with clock skew, InResponseTo correlation and replay protection, encryption of assertions, signed AuthnRequests, and the handling of IdP-initiated vs SP-initiated flows. The release notes say nothing about any of this. We must verify rather than assume.
• Auto-create user resolution is a privilege-escalation surface. If accounts are created on first assertion and mapped by e-mail, an IdP that lets users set an unverified e-mail (or a second IdP tenant asserting an already-taken address) can produce account takeover or duplicate identities. Needs allow-listing of domains, verified-email preconditions, and a decision on e-mail-change behaviour (link vs. create-new).
• RelayState handling must not become an open redirect or a panel-confusion vector.
• Filament v5 maturity is the gating question. If v5 is recent, we are adopting a new release of a package against a new major of its host framework simultaneously — two immature variables at once.
• No SLO / logout / session-invalidation is mentioned. SAML Single Logout is frequently required in enterprise security reviews; its absence is a likely procurement blocker.

Key questions to put to the maintainer / our own spike

• Minimum PHP and Laravel versions; which Filament v5 minor is tested; is v5 GA or pre-stable at the time we adopt?
• Test coverage and CI: are there integration tests against a real IdP (e.g. Keycloak/SimpleSAMLphp) or only unit tests of config parsing?
• Does it enforce signature validation on assertions and responses, audience restriction, and replay protection? Are AuthnRequests signed? Are assertions accepted encrypted?
• Does it support IdP-initiated flows, SLO, and multiple IdPs per panel?
• What are the events/hooks for provisioning (pre-create, pre-link, post-login) so we can add domain allow-listing, audit logging, and role mapping?
• E-mail change / NameID change semantics — does it create a new identity or error?
• License, release cadence, security-disclosure policy, and how prior majors were supported after a new Filament major landed.
• Can saml2_identities rows be reconciled/backfilled if we later migrate to a different SP library? (Exit cost.)

Integration Approach

Stack fit

• Assumes Laravel with Filament v5 panels; PHP version and Laravel major must be confirmed before we commit (not stated in the notes).
• Composer-only: jeffersongoncalves/filament-saml2:"^3.0". Note the caret constraint will pull 3.x minors automatically — acceptable for patches, but we should pin to a reviewed commit/tag in production and gate upgrades through CI.
• Requires a published migration for saml2_identities; this becomes a first-class table in our schema and should be treated as owned data with its own retention/audit story, not an opaque vendor table.
• IdP configuration lives in config/env per tenant — secret material (IdP x509 certs, SP private key) must go to our secret manager, not .env files in the repo.

Migration path

• There is no migration path from earlier majors other than "you were on Filament 3/4, now you are on 5." If we are on Filament 4 today, this release is not adoptable until the Filament 4→5 upgrade happens; the two upgrades must be sequenced as one programme, not two.
• For greenfield Filament 5 panels, this is a clean add: install, migrate, register the plugin on the panel, configure one IdP, keep local auth enabled.
• If we already run SAML via another SP (e.g. Socialite-based or a bespoke implementation), the honest options are (a) run in parallel behind a feature flag and port identities via the polymorphic table, or (b) hard cutover at a maintenance window with a documented rollback. Parallel-run is strongly preferred given SSO is on the login path.

Compatibility

• Hard-couple our Filament version to this package's major (v3 ↔ Filament v5) and record that mapping in the dependency policy. Add a CI check that fails when Filament moves major without a matching filament-saml2 major.
• Translations ship for en/pt_BR/es. If we serve other locales, expect to contribute or override strings — small but worth budgeting.
• Verify PHP extension prerequisites of the underlying SAML toolkit (typically openssl, dom, sometimes xmlsec) in our container images and CI, not just locally.

Sequencing

1. Verify — spike branch: confirm PHP/Laravel/Filament v5 compatibility against our actual app skeleton; confirm the package installs and boots in CI.
2. Security review — read the assertion-validation path in both packages; run a test IdP (Keycloak) and attempt: unsigned assertion, wrong audience, replayed assertion, expired assertion, RelayState tampering, cross-tenant e-mail collision. This is the gate, not a nice-to-have.
3. Pilot — one internal panel, one IdP, local auth retained as fallback, audit logging on every provisioning event.
4. Provisioning policy — decide and document auto-create rules (domain allow-list, verified-email requirement, role mapping defaults = least privilege, behaviour on e-mail change).
5. Tenant rollout — enable per-panel options panel by panel; add a second IdP tenant only after the first is stable.
6. Harden — cert-rotation runbook, monitoring/alerts, then decide on SSO-only vs. permanent local-admin break-glass.
7. Decommission local auth for SSO-mandated panels last, once we have a quarter of clean operation.

Operational Impact

Maintenance

• Ongoing cost is low in code terms but non-zero in dependency hygiene: this package plus the underlying SAML library, both needing to track Filament and Laravel majors. Budget an upgrade task at every Filament major, and expect the package's major number to move with it.
• Schema ownership: the saml2_identities table will accumulate rows; we need retention, cleanup, and a plan for orphaned identities when users are deleted (polymorphic relations do not cascade automatically — confirm).
• We inherit the vendor's security-release latency. If a SAML vulnerability lands in the underlying toolkit, our exposure window is the maintainer's turnaround, not ours. Mitigation: watch the upstream repo, and keep an exit plan to a first-party or commercially supported SAML library.

Support

• Community/OSS support model: GitHub issues, no SLA, no vendor to escalate to. Acceptable for internal admin SSO; harder to defend if this fronts customer-facing or revenue-critical access.
• Internally, SSO becomes a tier-1 support topic — "I can't log in" is your highest-severity ticket class. Runbook and on-call ownership must be assigned before go-live, not after.
• Keep a documented, tested break-glass path (a local admin account with strong MFA, or CLI-level access) so an IdP outage is not a full outage.

Scaling

• Technically near-trivial to scale: the SP is stateless request/response handling; no new service, no queue, no storage tier beyond a small table. It scales with the app.
• Two real scaling caveats: (1) session affinity / shared session store — across multiple app nodes, RelayState and SAML session correlation require a shared session backend, so confirm Redis/DB sessions are configured before horizontal scaling; (2) IdP tenant fan-out — one login button per IdP tenant means the login page grows with customer count; plan for an IdP-discovery step or per-tenant login URLs rather than an unbounded button list.

Failure modes (ranked by likelihood × impact)

1. IdP signing-certificate rotation — the single most common SAML outage. Expiry or rotation without updating our config breaks all logins for that tenant. Needs an owned calendar entry plus expiry monitoring, and a config path that does not require a deploy.
2. Clock skew — assertions rejected as not-yet-valid; verify NTP on app hosts and understand the tolerance window.
3. Provisioning errors — duplicate users after e-mail/NameID change, role mapping defaulting too high, cross-tenant e-mail collision. Mitigate with least-privilege defaults and audit logs.
4. RelayState / panel mis-resolution — user lands on the wrong panel or a broken redirect; validate against an allow-list.
5. Upstream abandonment or lag — package not updated for the next Filament major, blocking our framework upgrades. This is the risk that most affects the roadmap, and it is a scheduling risk more than a runtime one.
6. No SLO — stale sessions persist after IdP-side deprovisioning; if that matters contractually, we need a compensating control (short session lifetimes, periodic re-validation).
7. Configuration drift across environments — staging pointed at the production IdP or vice versa; put IdP config under the same review process as other auth config.

Ramp-up

• For a Laravel/Filament team, this is a low-ceremony adoption: one developer can integrate it in days. The learning curve is not the package — it is SAML itself and the IdP-side configuration, which is usually owned by a customer's IT team and is where the calendar time goes.
• Plan for: one engineer to own the integration, one to own the security review (or an external review), and a named owner for the IdP-certificate rotation runbook. Do not let the ease of composer require create the impression that this is a low-stakes change — it sits on the authentication path and inherits the availability expectations of login.
• Business upside worth weighing against the risk: SAML SSO is commonly a procurement gate for enterprise and regulated buyers, and per-tenant IdP support plus JIT provisioning is exactly the shape those buyers ask for. On that basis the package is a reasonable accelerator — provided the security review in step 2 is treated as a hard gate rather than a formality, and provided we accept the single-maintainer dependency knowingly, with an exit path documented.