This is a package to provide a simple SPID authentication system to web applications based on Laravel.
-
Before installing this package patching must be enabled in
composer.json
. This is necessary because this patch has to be applied to onelogin/php-saml for SPID compatibility.Edit your
composer.json
like this:... "extra": { "enable-patching": "true" }, ...
or simply run:
composer config extra.enable-patching true
.Since this package is still in beta,
minimum-stability
option must be set tobeta
and theprefer-stable
option must be set totrue
incomposer.json
.These options can be set by running:
composer config minimum-stability beta composer config prefer-stable true
For Windows only
Composer needs the patch command to be installed (it is not part of Windows). To enable it install Git then add the C:\Program Files\Git\usr\bin folder to the system path.
This installation step will be removed before the first stable release of this package.
-
Require this package with composer.
composer require italia/spid-laravel
-
Exclude the URIs used by this package from CSRF protection because the the Identity Providers can't know what CSRF token include in their POST requests sent to your routes.
In your
app/Http/Middleware/VerifyCsrfToken.php
set'/spid/*'
as an element of the$except
array.<?php namespace App\Http\Middleware; use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware; class VerifyCsrfToken extends Middleware { /** * The URIs that should be excluded from CSRF verification. * * @var array */ protected $except = [ '/spid/*' ]; }
Publish the configuration with:
php artisan vendor:publish --provider="Italia\SPIDAuth\ServiceProvider"
This will create a spid-auth.php
file in your config
directory where you can
set these options:
Service Provider options
sp_entity_id
: Service Provider Entity ID;sp_organization_name
: Service Provider Organization Name;sp_organization_display_name
: Service Provider Organization Display Name;sp_organization_url
: Service Provider Organization URL;sp_requested_attributes
: SPID attributes requested to Identity Providers.
These options must be set accordingly to the official SPID technical rules.
The values entered in the config file will be used to generate the SAML Service
Provider metadata at runtime. The generated metadata will be available in XML
format at /spid/metadata
.
Due to limitations of onelogin/php-saml,
only the HTTP-POST
binding is supported for the AssertionConsumerService
endpoint and the HTTP-Redirect
for the the SingleLogoutService endpoint.
Application options
middleware_group
: the middleware group assigned to the packages routes. The default value isweb
which comes with Laravel out of the box and provides some common features like session management and cookies. You can add more middlewares using an array butweb
must be always included.routes_prefix
: the route prefix applied to the package routes. If you change the defaultspid
value make sure to reflect this change in theapp/Http/Middleware/VerifyCsrfToken.php
file as described above. Please note that in this document the value is assumed to bespid
.login_view
: the view to display when the user is redirected by the packagespid.auth
middleware (see Middleware section below). The default view isspid-auth::login-spid
.after_login_url
: the URL to redirect to after a successful login. If the login process is triggered by the packagespid.auth
middleware, the user will be redirected to the original destination. Default value is/
.after_logout_url
: the URL to redirect to after a successful logout. Default value is/
.
Please note that the php artisan vendor:publish --provider="Italia\SPIDAuth\ServiceProvider"
command will copy some static assets to your public
directory. You can publish
configuration and assets separately adding --tag=spid-config
and
--tag=spid-assets
options on the command line.
Due to the specific working mode of the SameSite cookie parameter, this package
can only work with lax
or none
policy. Thus the config option
session.same_site
MUST be set accordingly.
The SPID authentication process is completely agnostic about the authentication
system of your application. If you plan to integrate your authentication system
with SPID, you can listen to the LoginEvent
and LogoutEvent
(see
Events and Example).
If you need more customization in the authentication logic of your application,
you can use the methods available in the SPIDAuth
Service Provider.
First you need an instance of the Service Provider from the Service Container:
$SPIDAuth = app('SPIDAuth');
The following public methods can be used in your application.
Method | Description |
---|---|
login | Show the configured login_view with a SPID button, if authenticated redirect to after_login_url . |
doLogin | Attempt login with the SPID Identity Provider in the current request and redirect to the intended or configured after_login_url if authenticated. |
acs | Process the POST response from Identity Providers, set session variables and redirect to the intended or configured after_login_url . |
logout | Attempt logout with the SPID Identity Provider stored in the current session. |
isAuthenticated | Check if the current session is authenticated with SPID. |
metadata | Show metadata for this SPID Service Provider. |
providers | Identity Providers list in JSON format used by the SPID smart button. |
getSPIDUser | Return the current authenticated SPIDUser or null if not authenticated. |
You can display a simple SPID access button by including the
spid-auth::spid-button
view in your template:
@include('spid-auth::spid-button')
Optionally you can specify the button size (s
, m
, l
or xl
):
@include('spid-auth::spid-button', ['size' => 'm'])
To display the button dropdown right aligned you can set the rightAlign
parameter to true
.
@include('spid-auth::spid-button', ['rightAlign' => true])
Your templates must include a @stack('styles')
directive inside the head
tag and a @stack('scripts')
directive inside the body
tag.
The button is the official spid-sp-access-button and requires jQuery.
Scenario
- The user clicks on the button and a list of Identity Provider is displayed;
- The user choose an Identity Provider and is redirected to the corresponding login page;
- After a successful login the user is redirected to the URL specified in the
after_login_url
option and aLoginEvent
is triggered.
You can assign the spid.auth
middleware to specific routes like so:
Route::get('private', 'PrivateController@show')->middleware('spid.auth');
Or you can assign the spid.auth
middleware to application controllers:
class PrivateController extends Controller
{
/**
* Instantiate a new controller instance.
*
* @return void
*/
public function __construct()
{
$this->middleware('spid.auth');
}
}
Scenario
- The user requests a resource which
spid.auth
middleware is assigned to. - The user is redirected to
/spid/login
and the view specified inlogin_view
option is displayed; - The user choose an Identity Provider and is redirected to the corresponding login page;
- After a successful login the user is redirected to the URL of the original
resource and a
LoginEvent
is triggered.
LoginEvent
and LogoutEvent
can be listened to get some useful information
about the authenticated user. Both events share these methods:
getSPIDUser()
returns aSPIDUser
object filled with the attributes specified in thesp_requested_attributes
option and returned by the Identity Provider;getIdp()
returns the entityName of the Identity Provider.
To listen to both events using the same object, you can use an Event Subscriber class that can be defined as follow:
<?php
namespace App\Listeners;
use Italia\SPIDAuth\Events\LoginEvent;
use Italia\SPIDAuth\Events\LogoutEvent;
class SPIDEventSubscriber
{
/**
* Handle SPID login events.
*/
public function onSPIDLogin($event) {
// $event->getSPIDUser() and $event->getIdp() are available here
// your application logic goes here
}
/**
* Handle SPID logout events.
*/
public function onSPIDLogout($event) {
// $event->getSPIDUser() and $event->getIdp() are available here
// your application logic goes here
}
/**
* Register the listeners for the subscriber.
*
* @param Illuminate\Events\Dispatcher $events
*/
public function subscribe($events)
{
$events->listen(
'Italia\SPIDAuth\Events\LoginEvent',
'App\Listeners\SPIDEventSubscriber@onSPIDLogin'
);
$events->listen(
'Italia\SPIDAuth\Events\LogoutEvent',
'App\Listeners\SPIDEventSubscriber@onSPIDLogout'
);
}
}
The SPIDEventSubscriber
class must be added to the $subscribe
array in
app/Providers/EventServiceProvider.php
:
protected $subscribe = [
'App\Listeners\SPIDEventSubscriber'
];
The SPIDUser
class provides <attribute>
properties for the attributes
specified in the sp_requested_attributes
option (e.g. for the name
attribute
you find a SPIDUser->name
property). If the attribute is not available null
is returned.
Simply provide your users a link pointing to /spid/logout
.
Scenario
- The user clicks on a link pointing to
/spid/logout
; - After a successful logout the user is redirected to the URL specified in the
after_logout_url
option and aLogoutEvent
is triggered.
This package comes with a simple set of controllers, views and routes that can be run as an example in a fresh installed Laravel application.
To publish the needed files run the command:
php artisan spid-auth:example
This will create the following files:
app/Http/Controllers/HomeController.php
app/Http/Controllers/PrivateController.php
app/Listeners/SPIDEventSubscriber.php
resources/views/layouts/app.blade.php
resources/views/home.blade.php
resources/views/private.blade.php
Next add the SPIDEventSubscriber
class in
app/Providers/EventServiceProvider.php
as described above.
You can open storage/logs/laravel.log
to read some example informations logged by the
SPIDEventSubscriber
.
Make sure to set your timezone in app/config/app.php
because the id of every
assertion consumed is cached to prevent replay attacks. This feature rely on a
correct timezone configuration of your app.
As required in the SPID technical specifications, the Service Provider MUST accept messages in HTTPS only.
According to this requirement, some cookies in this package are created with
Secure
policy, thus the authentication does not work in an unsecure context.
In the
spid-idps.php
file are defined the official
SPID Identity Providers.
For testing purposes, this file includes also a test Identity Provider. Refer to the SPID Test Environment to get more informations about SPID authentication testing.
The test Identity Provider can be enabled/disabled using the test_idp
entry
in your config/spid-auth.php
file.
'test_idp' => [
'entityId' => '<Test IdP entityId>',
'sso_endpoint' => '<Test IdP SingleSignOnService endpoint>',
'slo_endpoint' => '<Test IdP SingleLogoutService endpoint>',
'x509cert' => '<Test IdP x509 certificate>',
],
Set 'test_idp' => false
to disable.
In the
spid-auth.php
file are defined the X.509 certificate and the private key of the Service
Provider. Please note that the values provided are only for testing purposes and
can't be used in production.
You can set your own X.509 certificate and private key in the
config/spid-auth.php
file of your application (which overrides the one in the
package).
The X.509 certificate and the private key can be configured as strings or as
paths to files. If both are specified in your config/spid-auth.php
then the
ones specified as strings will take precedence.
Change the values and keep the private key secret.
BSD-3-Clause License
is generally applied to all the code in this repository if not otherwise specified.
MIT License
is applied to some portions of code as reported in
this README.
SIL Open Font License 1.1
is applied to the Titillium font included from CSS files.