README

Sign citizens in to Filament panels with SPID, the Italian public digital identity system, over SAML 2.0. The SAML side is italia/spid-laravel; this plugin puts the SPID button on the panel login page, turns a validated SPID identity into a login on the panel's guard, and adds an installer, a doctor and an adapter for AgID's metadata validator.

A community package maintained by Offline Agency, released under the MIT license. It is not an official Filament plugin and not an AgID product, and installing it does not make a service accredited to SPID: that takes AgID's own procedure (see Testing with AgID's tools).

Italiano: guida in italiano.

Stable release 1.0.0. GitHub release published on 16 October 2026 at 18:17:21 UTC (prerelease: false). Separately verified on 18 October 2026: Packagist metadata lists 1.0.0, with source and dist reference 99f80235a6be15b6365840f46f160476e2fdb38e. Install using the complete quick start below: the stable plugin still needs the pinned, patched italia/spid-laravel fork tracked in #16. Registry publication alone does not prove dependency resolution in your application. 0.1.x is no longer maintained (SECURITY.md).

Requirements

	Supported (every combination tested in CI)
PHP	8.3, 8.4, 8.5
Laravel	12.x, 13.x
Filament	3.x, 4.x, 5.x
SPID service provider	public and private SPs; aggregators and operators (gestori) are not covered

Laravel 11 left security support on 12 March 2026 and PHP 8.2 leaves it on 31 December 2026 (Laravel support policy, PHP supported versions, checked on 11 October 2026), so neither is supported by 1.x.

Who does what

	Responsible
SAML: AuthnRequest, Response validation, signatures, metadata; the SPID patch to `onelogin/php-saml`; the IdP list	italia/spid-laravel
The SPID button on the panel; login on the panel guard; fail-closed errors; optional provisioning; events; `filament-spid:install`, `filament-spid:doctor`, `filament-spid:metadata:validate`	this plugin
Who may enter (`canAccessPanel()`); the SP's identity, contacts and key pair; sessions; logout policy; data retention; HTTPS and proxies; AgID acceptance	your application and your organisation

Quick start

You need a Laravel 12 or 13 application with a Filament panel (php artisan filament:install --panels), the SP's signing key pair (see Certificates) and the SP's real data (organisation, IPA code or VAT number, contact email).

# Run in the root of a Laravel 12 or 13 application with a Filament panel.

# 1. italia/spid-laravel with the SPID patch for php-saml ^4.3.1: until
#    upstream tags a release, the offline-agency fork at a pinned commit.
composer config repositories.spid-laravel vcs https://github.com/offline-agency/spid-laravel
composer config allow-plugins.cweagans/composer-patches true
composer config extra.enable-patching true --json
composer require "italia/spid-laravel:dev-feat/laravel-13#b8dd1a484d8e6551a1a84e90220c2e9dc0d0a0fe as 2.1.0-beta" --no-update

# 2. The plugin.
composer require offline-agency/filament-spid:^1.0

# 3. Install and configure from setup.json (copy examples/setup.public.json or
#    setup.private.json from the package and fill in your SP's real data and
#    key pair paths). --dry-run shows the plan and writes nothing.
php artisan filament-spid:install --panel=admin --input=setup.json --dry-run
php artisan filament-spid:install --panel=admin --input=setup.json

# 4. Check.
php artisan migrate
php artisan filament-spid:doctor

Why step 1: the latest published italia/spid-laravel, v2.1.0-beta (checked on 18 October 2026), pins onelogin/php-saml 4.1.0, affected by CVE-2025-66475. The fix is merged upstream (italia/spid-laravel#132) but not tagged; the fork is pinned to a commit whose patch URL is pinned too, so the SPID patch cannot change under you. Only italia/spid-laravel gets a dev constraint: your minimum-stability stays as it is. #16 tracks the switch to the tagged release.

Without --input the installer asks the questions. Either way it validates everything before writing, shows the plan, keeps existing files, registers the plugin after ->login(), exempts only the ACS from CSRF, and lists what it could not do safely as manual steps (then exits with 1). Running it again changes nothing.

Then decide who may enter. SPID proves who the citizen is, not what they may do:

use Filament\Models\Contracts\FilamentUser;
use Filament\Panel;

class User extends Authenticatable implements FilamentUser
{
    protected $fillable = ['name', 'email', 'password', 'fiscal_code', 'spid_data'];

    protected $casts = ['spid_data' => 'array'];

    public function canAccessPanel(Panel $panel): bool
    {
        // Your own rule, e.g. a role column your application defines and manages.
        return $panel->getId() === 'admin' && $this->role === 'administrator';
    }
}

Accounts are matched by fiscal code, never by email. No account is created for a SPID citizen unless you turn auto_create_users on, and even then canAccessPanel() decides who gets in.

Documentation

Installation and configuration: the installer and its input, manual installation, public and private SPs, certificates, CSRF, proxies.
Configuration reference: every key, SPID levels, data minimisation, field mapping, multiple panels, the SPID button.
How login works: the success boundary, fail-closed errors, guards and sessions, provisioning, events and transactions, local logout and SLO.
Diagnostics: filament-spid:doctor and filament-spid:metadata:validate.
Testing with AgID's tools: the local lab, spid_sp_test, the AgID Validator, the acceptance test. What has been verified.
Production checklist · Troubleshooting · FAQ · Upgrading from 0.1.x

AI coding agents: the package ships Laravel Boost guidelines and a spid-integration skill, which php artisan boost:install installs when the package is a direct dependency.

Development

composer test
composer analyse
vendor/bin/pint --test
node --test 'tests/js/*.test.mjs'

See CONTRIBUTING for the local setup that mirrors CI, the SPID lab and the release flow.

Changelog, security, support

CHANGELOG
Security policy: report vulnerabilities by email, never in a public issue.
Questions and bugs: GitHub issues or support@offlineagency.it.
Contributing and the Code of Conduct.

Credits

Offline Agency and all contributors
italia/spid-laravel, the SAML integration this plugin builds on
italia/spid-sp-test and italia/spid-saml-check, the validation tools

License

MIT. See LICENSE.md.

offline-agency / filament-spid

Package info

Security

Fund package maintenance!

Statistics