offline-agency / spid-laravel-trentino

v2.3.0 2026-10-07 21:12 UTC

Requires

• php: ^8.4
• illuminate/auth: ^12.69|^13.30
• illuminate/cache: ^12.69|^13.30
• illuminate/config: ^12.69|^13.30
• illuminate/console: ^12.69|^13.30
• illuminate/contracts: ^12.69|^13.30
• illuminate/database: ^12.69|^13.30
• illuminate/encryption: ^12.69|^13.30
• illuminate/events: ^12.69|^13.30
• illuminate/http: ^12.69|^13.30
• illuminate/log: ^12.69|^13.30
• illuminate/routing: ^12.69|^13.30
• illuminate/session: ^12.69|^13.30
• illuminate/support: ^12.69|^13.30
• illuminate/view: ^12.69|^13.30
• jumbojett/openid-connect-php: ^1.0.2

Requires (Dev)

• firebase/php-jwt: ^7.2
• larastan/larastan: ^3.12
• laravel/pint: ^1.32
• orchestra/testbench: ^10.2|^11.0
• pestphp/pest: ^4.3|^5.0

MIT

• Offline Agency

• laravel
• SPiD
• oidc
• aac
• openid-connect
• pkce
• pubblica-amministrazione
• trentino

Published on Packagist.org on 2026-10-07 21:12 UTC

README

SPID (Sistema Pubblico di Identità Digitale) login for Laravel applications through AAC Trentino. The package runs the OpenID Connect authorization code flow with PKCE, creates or updates the local user by fiscal code, and keeps the session and tokens fresh with two middleware.

Funding and reuse

This package was developed with funding from the Consorzio dei Comuni Trentini and is released as open source software for reuse by public administrations and other parties, in line with art. 69 of the Italian CAD (Codice dell'Amministrazione Digitale).

Requirements

Requirement	Supported versions
PHP	8.4, 8.5
Laravel	12 (12.69+), 13 (13.30+)
AAC Trentino	An OIDC client with the redirect URI of your callback route and the scopes openid profile.codicefiscale.me email offline_access

Every combination (PHP 8.4 and 8.5, Laravel 12 and 13, lowest and latest dependencies) runs in CI.

Quick start

1. Install

composer require offline-agency/spid-laravel-trentino

2. Publish the configuration and the migration, then migrate

php artisan vendor:publish --tag=spid-laravel-trentino-config
php artisan vendor:publish --tag=spid-laravel-trentino-migrations
php artisan migrate

3. Configure .env

SPID_TRENTINO_CLIENT_ID=your-client-id
SPID_TRENTINO_CLIENT_SECRET=your-client-secret
SPID_TRENTINO_REDIRECT_URI=https://your-app.test/spid/callback
SPID_TRENTINO_PROVIDER_URL=https://aac-test.cloud-test.tndigit.it

Register the same redirect URI on AAC. The provider URL above is the AAC test environment.

4. Prepare the user model

protected $fillable = [
    'name', 'email', 'password',
    'fiscal_code', 'surname', 'preferred_username', 'locale', 'zoneinfo',
];

protected function casts(): array
{
    return [
        'password' => 'hashed',
        'spid_profile' => 'array',
    ];
}

5. Protect your routes and add the login button

The middleware aliases are registered by the package; put spid.refresh before spid.valid. If SPID is your only login, send guests to it in bootstrap/app.php (Laravel's auth middleware otherwise redirects to a route named login):

use Illuminate\Foundation\Configuration\Middleware;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->redirectGuestsTo(fn () => route('spid.login'));
})

Then add the button to a view:

<x-spid-laravel-trentino::login-button />

Minimal example

routes/web.php:

use Illuminate\Support\Facades\Route;

Route::view('/', 'welcome');

Route::middleware(['web', 'auth', 'spid.refresh', 'spid.valid'])->group(function () {
    Route::get('/area-riservata', fn () => 'Benvenuto, '.auth()->user()->name);
});

resources/views/welcome.blade.php:

@if (session()->has(\OfflineAgency\SpidLaravelTrentino\SessionKeys::ERROR))
    <p>{{ session(\OfflineAgency\SpidLaravelTrentino\SessionKeys::ERROR) }}</p>
@endif

@auth
    <form method="POST" action="{{ route('spid.logout') }}">
        @csrf
        <button type="submit">Esci</button>
    </form>
@else
    <x-spid-laravel-trentino::login-button />
@endauth

Opening /area-riservata as a guest sends the user to spid.login (through auth and redirectGuestsTo() from step 5). Clicking the button starts the SPID login at /spid/login; after AAC the user returns to /spid/callback, is created or updated by fiscal code, logged in, and redirected to the page they asked for.

Documentation

For applications using the package:

• Installation: requirements, publishing, environment variables, AAC registration, middleware
• Configuration: every configuration key and the default routes
• User model: columns, $fillable, casts, how users are matched
• Authentication flow: login, callback and logout sequences
• Session and tokens: session keys, expiry, refresh
• Middleware: spid.refresh and spid.valid
• Events: SpidTrentinoLoggedIn and SpidTrentinoLoggedOut
• User DTO: SpidTrentinoUser and the AAC claims
• Extending: custom controller, own routes, login button, service API
• Troubleshooting: log messages, causes and fixes
• Security: what is validated, logging, production checklist
• Transaction log: SPID/CIE OIDC retention policy (24 months), pruning, integrity checks

For maintainers:

• Architecture: class map and container bindings
• Development: tests, quality gates, CI, releases
• Known issues: open issues in 2.0 and 1.x problems fixed in 2.0

Also: UPGRADE.md (1.x to 2.0), CHANGELOG.md, CONTRIBUTING.md.

Security

Report vulnerabilities privately, see SECURITY.md (contact: [e-mail]).

Credits

• Giacomo Fabbian
• All Contributors

About us

Offline Agency is a web design agency based in Padua, Italy. You'll find an overview of our projects on our website.

License

The MIT License (MIT). Please see License File for more information.