Filament Spid Laravel Package

Technical Evaluation

Architecture fit filament-spid 1.0.0 is not a standalone auth library: it is a Filament panel integration layer over italia/spid-laravel, which in turn wraps onelogin/php-saml for the SAML 2.0 SP role. The 1.0 architecture makes that layering explicit and, correctly, narrows the plugin's job: italia/spid-laravel owns the ACS endpoint (spid-auth_acs) and emits auth events, while the plugin ships HandleSpidLogin / HandleSpidLogout listeners that provision the user, authenticate on the panel guard and call FilamentUser::canAccessPanel() before granting access. For any Italian public-sector or SPID-mandated service already on Filament, this is a good fit — it avoids hand-rolling SAML plumbing and removes the per-application listener code that 0.1.x required. The plugin is also usable outside a SPID panel (SpidPlugin::resolve() returns null), which keeps blast radius small on multi-panel apps.

Integration feasibility Feasible but with an unusually heavy prerequisite chain for a Composer package. Installation requires: PHP 8.3+, Laravel 12–13, minimum-stability: beta, cweagans/composer-patches enabled, and a patched fork of italia/spid-laravel, because every published upstream version pins onelogin/php-saml 4.1.0 (CVE-2025-66475) and Composer refuses to install it. That is a supply-chain and governance decision, not a composer require. The filament-spid:install command materially improves feasibility — validated input (paths to key material, never the material itself), a shown plan, non-destructive publishing, idempotent re-runs, explicit manual steps and exit 1 on anything unsafe. But it edits bootstrap/app.php and the panel provider via PHP's tokenizer; that must be reviewed in a PR and backed by version control, not run blind in CI.

Technical risk

• Compliance risk (highest). SPID is a regulated identity scheme. The metadata validator deliberately records HOSTED_VALIDATOR_NOT_RUN and FORMAL_AGID_ACCEPTANCE_NOT_OBTAINED; passing it is not AgID accreditation. Plan for the AgID test cycle as a separate track.
• Fail-closed defaults are correct but disruptive. Logins are refused below filament-spid.minimum_level (default SpidL2) while the library defaults to SpidL1; auto_create_users now defaults to false. Both are safety-positive and both will look like outages to users if not configured.
• Dependency fragility. A private fork plus a patch for a CVE, plus a pinned spid_sp_test 1.2.18 with a xmlsec1 system dependency, is a lot of surface to keep current.
• Version floor decisions. Dropping Laravel 11 and PHP 8.2 is defensible (EOL / advisories) but forces an upgrade on any host app on 11.x before this package can be adopted at all.
• Data mapping change. Email fallback moves from <fiscal code>@spid.local to @spid.invalid; with update_user_data on, existing accounts change on next login. Anything keyed on email will drift.
• Incomplete notes. The release text is truncated mid-sentence in the "Changed" section (jQuery asset bundling); get the full changelog before sign-off.

Key questions

1. Who owns and maintains the italia/spid-laravel fork and the php-saml patch, and what is the exit plan when upstream ships a fixed release?
2. Is minimum-stability: beta + patching acceptable under our dependency policy, and who signs that off?
3. Which panels and guards are in scope, and is more than one SPID panel needed (filament-spid.panel pins exactly one)?
4. Do we already hold an AgID-registered SP with a valid key pair and metadata, or does that registration start now?
5. Do any flows require SpidL3, and what is our answer if sp_spid_level is provisioned as L1 by default?
6. Are existing user records keyed on email, and does update_user_data rewrite them?
7. Can our CI and production images supply xmlsec1 and the pinned spid_sp_test, and do we allow outbound HTTPS to IdP metadata URLs?
8. Who is on point for the AgID test evidence pack and the production checklist?

Integration Approach

Stack fit Target the supported matrix explicitly: PHP 8.3–8.5, Laravel 12–13, Filament 3–5; CI covers every combination, which is a strong signal. Users table: the new default field_mapping maps password to RandomPassword so auto_create_users works against Laravel's stock users table (password NOT NULL) — this removes a common custom-mapping chore. Use filament-spid.sp_profile and filament-spid.deployment to declare intent (public SP with IPA code vs private with VAT number) rather than encoding it in prose. Apply data minimisation up front via store_spid_data / spid_data_attributes instead of accepting the eight-attribute default.

Migration path (0.1.x → 1.0.0) Treat this as a breaking migration, not an upgrade:

1. Raise PHP to 8.3+ and Laravel to 12+ — hard blockers.
2. Add the patched italia/spid-laravel fork, enable patching and beta stability.
3. Rename config: redirect_after_login → spid-auth.after_login_url, spid_level → spid-auth.sp_spid_level, providers → SpidPlugin::providers(); drop the corresponding env vars.
4. Set sp_spid_level to SpidL2 or higher (library default is L1 and will now be refused).
5. Decide auto_create_users deliberately (default is now off).
6. Delete any application-owned listeners — HandleSpidLogin/HandleSpidLogout replace them; opt out only via filament-spid.register_listeners if you truly need custom behaviour.
7. Drop any custom ACS route or SpidPlugin::acsRoute() usage; the library owns spid-auth_acs. Re-check CSRF exemptions — only the ACS should be exempt.
8. Reconcile @spid.local → @spid.invalid before enabling update_user_data in production.
9. Verify ->login() chaining still leaves the SPID login page intact (a warning now logs when it is replaced).

Compatibility The contract is now SemVer from 1.0.0, which is the single biggest improvement for planning: future 1.x upgrades should be non-breaking. Compatibility risk concentrates in three places — the fork/patch, the pinned spid_sp_test version and its xmlsec1 dependency, and the panel/guard assumptions in the listener.

Sequencing

1. Inventory host apps: PHP, Laravel, Filament, panel count, existing SPID usage.
2. Confirm SPID SP registration, key pair and metadata ownership; open the AgID test track now (longest lead time).
3. Branch: add fork + patches, dry-run filament-spid:install --dry-run, review the diff, then apply with --migrate.
4. Run filament-spid:doctor --strict in CI; fail the build on non-zero exit. Track the JSON schema_version and pin against it.
5. Run filament-spid:metadata:validate against our published metadata; archive the report (SHA-256, versions, profile, timestamp) as evidence.
6. Exercise the flow against test IdPs using the shipped tools/spid lab and the spid-validation workflow, including the failure sentinels.
7. Stage the panel cutover; keep showSpidButton(false) as the rollback lever.
8. Production: run the checklist, remove test IdPs (the doctor flags them), verify HTTPS and session cookie settings, confirm key pair is not the shipped example.
9. Post-launch: monitor access_denied, level-mismatch refusals and auth failure rates as distinct signals.

Operational Impact

Maintenance Two upstreams to watch (the italia/spid-laravel fork and onelogin/php-saml), plus a patch we must retire once upstream fixes CVE-2025-66475. Budget recurring effort for: certificate/metadata rotation, spid_sp_test version bumps, the PHP 8.3 floor (and 8.2 security EOL on 31 Dec 2026), and advisory-floor checks the doctor now automates. Release automation (label-driven tagging, notes from the changelog) and SECURITY.md/CODE_OF_CONDUCT.md indicate a maintained project, but this is a single-maintainer-risk profile until proven otherwise.

Support filament-spid:doctor is the standout operational feature: read-only, no network, stable JSON schema_version, exit codes 0/1/2, --strict for CI gating, and it judges the php-saml patch by the metadata the library actually builds rather than by PATCHES.txt — that is the right test. filament-spid:metadata:validate fails closed (missing tool, wrong version, crash, timeout, missing xmlsec1, unreadable report → exit 2, never a pass) and uploads nothing. Documentation in docs/ plus an Italian guide lowers first-line support load; assume the Italian material is the authoritative source and that English drift is possible. Boost resources are a developer-experience nicety only — no runtime dependency, do not count them in an operational plan.

Scaling No unusual scaling characteristics: SPID is a redirect-based SAML handshake per login, and the package adds no background workers, queues or storage. Two real considerations: the once-per-hour configuration warnings use the cache, so a shared cache store is required for them to behave across nodes; and metadata validation makes outbound HTTPS requests with TLS verification, no redirects and size/time limits, so egress allowlisting to IdP metadata hosts is the only network change to plan.

Failure modes

• Composer refuses to install without the fork, patching and beta stability — surfaces at build time, which is the best place for it.
• Level mismatch: sp_spid_level below minimum_level, or a non-URI minimum, refuses every SPID login. Fail-closed and correct, but reads as a total outage; alert on it.
• auto_create_users: false silently blocks first-time citizens — a top-tier support ticket generator after the default flip.
• Panel misconfiguration: a filament-spid.panel naming no registered panel throws SpidPanelNotFoundException instead of falling back to the default guard — good, because the old behaviour could authenticate on the wrong guard.
• Email remapping to @spid.invalid can create duplicate or orphaned accounts if lookups assume email stability.
• Tokenizer edits during install can corrupt bootstrap/app.php or the panel provider; mitigate with --dry-run, VCS, and code review.
• IdP unreachable at logout still ends the local session — acceptable degradation, but leaves a live SPID session at the IdP; document the citizen-facing behaviour.
• Validator false confidence: a passing report is explicitly not AgID acceptance; treating it as sign-off is the most likely process failure.

Ramp-up Moderate to high. SAML/SPID domain knowledge and Italian regulatory context are the real cost, not Laravel familiarity. A single-panel stock-users application should reach a working staging login in roughly a day using the installer and quickstart; the AgID test-and-evidence cycle is the multi-week critical path and should be resourced independently of the engineering work. Recommendation: adopt, contingent on (a) an accepted dependency-policy exception for the fork, patch and beta stability, (b) Laravel 12+/PHP 8.3+ confirmed across all in-scope apps, (c) doctor --strict wired into CI, and (d) the AgID track opened before the first production cutover. Obtain the untruncated changelog before final sign-off.