intervieweb / spid-php-lib
PHP package for SPID authentication
Requires
- php: ^7.1 || ^8.0
- ext-dom: *
- ext-openssl: *
- ext-simplexml: *
- ext-zlib: *
- psr/log: 1.1.4 || ^2.0 || ^3.0
- robrichards/xmlseclibs: ^3.0
Requires (Dev)
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10
- squizlabs/php_codesniffer: *
This package is not auto-updated.
Last update: 2024-11-04 17:43:57 UTC
README
Main differences with official release:
- implements logging
- uses PSR-12 style guide
spid-php-lib
PHP package for SPID authentication.
This PHP package is aimed at implementing SPID Service Providers. SPID is the Italian digital identity system, which enables citizens to access all public services with a single set of credentials. This package provides a layer of abstraction over the SAML protocol by exposing just the subset required in order to implement SPID authentication in a web application.
Alternatives for PHP:
- spid-php based on SimpleSAMLphp
- spid-php2 based on php-saml
Framework specific libraries and examples based on spid-php-lib:
- https://github.com/italia/spid-symfony-bundle
- https://github.com/simevo/spid-symfony3-example
- https://github.com/simevo/spid-wordpress
Alternatives for other languages:
Table of Contents
Repository layout
- bin/ auxiliary scripts
- example/ contains a demo application
- src/ contains the library implementation
- test/ contains the unit tests
Getting Started
Tested on: amd64 Debian 9.5 (stretch, current stable) with PHP 7.0.
Supports PHP 7.0, 7.1 and 7.2.
Prerequisites
sudo apt install composer make openssl php-curl php-zip php-xml
Configuring and Installing
NOTE: during testing, please use the test Identity Provider spid-testenv2.
-
Install with composer
composer require italia/spid-php-lib
-
(OPTIONAL) Manually generate key and certificate files for your Service Provider (SP).
Example:
openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -subj "/C=IT/ST=Italy/L=Milan/O=myservice/CN=localhost" -keyout sp.key -out sp.crt
This step can be skipped: the library takes care of this step automatically if you declare the optional
sp_key_cert_values
key in thesettings
array. Check the example in the Usage section for further details. -
Download the Identity Provider (IdP) metadata files and place them in a directory in your project, for example
idp_metadata
. A convenience tool is provided to download those of the production IdPs: vendor/italia/spid-php-lib/bin/download_idp_metadata.php, example usage:mkdir idp_metadata php vendor/italia/spid-php-lib/bin/download_idp_metadata.php ./idp_metadata
TEST ENVIRONMENT: If you are using spid-testenv2, manually download the IdP metadata and place it in your
idp_metadata
folder -
Make your SP known to IdPs: for production follow the guidelines at https://www.spid.gov.it/come-diventare-fornitore-di-servizi-pubblici-e-privati-con-spid
TEST ENVIRONMENT: simply download your Service Provider (SP) metadata and place it in the appropriate folder of the test environment. The test environment must be restarted after every change to the SP metadata.
Usage
All classes provided by this package reside in the Italia\Spid
namespace.
More detailed documentation is available in the SAMLInterface.php file.
Load them using the composer-generated autoloader:
require_once(__DIR__ . "/vendor/autoload.php");
The main class is Italia\Spid\Sp
(service provider).
Generate a settings array following this guideline
$settings = array( 'sp_entityid' => SP_BASE_URL, // preferred: https protocol, no trailing slash, example: https://sp.example.com/ 'sp_key_file' => '/path/to/sp.key', 'sp_cert_file' => '/path/to/sp.crt', 'sp_comparison' => 'exact', // one of: "exact", "minimum", "better" or "maximum" 'sp_assertionconsumerservice' => [ // order is important ! the 0-base index in this array will be used as ID in the calls SP_BASE_URL . '/acs', ... ], 'sp_singlelogoutservice' => [ // order is important ! the 0-base index in this array will be used as ID in the calls [SP_BASE_URL . '/slo', 'POST'], [SP_BASE_URL . '/slo', 'REDIRECT'] ... ], 'sp_org_name' => 'your organization full name', 'sp_org_display_name' => 'your organization display name', 'sp_key_cert_values' => [ // Optional: remove this if you want to generate .key & .crt files manually 'countryName' => 'Your Country', 'stateOrProvinceName' => 'Your Province or State', 'localityName' => 'Locality', 'commonName' => 'Name', 'emailAddress' => 'your@email.com', ] 'idp_metadata_folder' => '/path/to/idp_metadata/', 'sp_attributeconsumingservice' => [ // order is important ! the 0-base index in this array will be used as ID in the calls ["fiscalNumber"], ["name", "familyName", "fiscalNumber", "email", "spidCode"], ... ], // Time in seconds of skew that is acceptable between client and server when checking OnBefore and NotOnOrAfter // assertion condition validity timestamps, and IssueInstant response / assertion timestamps. Optional. // Default is 0. Acceptable range: 0-300 (inclusive) 'accepted_clock_skew_seconds' => 100 );
then initialize the main Sp class
$sp = new Italia\Spid\Sp($settings);
Don't want the library to generate .key and .crt files for you? Then remove the
sp_key_cert_values
key from thesettings
array, or decalre
// $autoconfiguration skips .key/.crt generation if set to false $sp = new Italia\Spid\Sp($settings, null, $autoconfiguration = false);
Performing login
// shortname of IdP, same as the name of corresponding IdP metadata file, without .xml $idpName = 'testenv'; // index of assertion consumer service as per the SP metadata (sp_assertionconsumerservice in settings array) $assertId = 0; // index of attribute consuming service as per the SP metadata (sp_attributeconsumingservice in settings array) $attrId = 1; // Generate the login URL and redirect to the IdP login page $sp->login($idpName, $assertId, $attrId);
Complete the login operation by calling
$sp->isAuthenticated();
at the assertion consumer service URL.
Then call
$userAttributes = $sp->getAttributes();
to receive an array of the requested user attributes.
Performing logout
Call
// index of single logout service as per the SP metadata (sp_singlelogoutservice in settings array) $sloId = 0; $sp->logout($sloId);
The method will redirect to the IdP Single Logout page, or return false if you are not logged in.
Complete API
Example
A basic demo application is provided in the example/ directory of this repository.
/example and /tests folders are NOT provided with the production version from packagist, remember to require the dev-develop
version or just clone this repository (advised)
To try it out:
-
Generate a test certificate and key pair with:
openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -subj "/C=IT/ST=Italy/L=Milan/O=myservice/CN=localhost" -keyout sp.key -out sp.crt
-
Adapt the hostname of the SP changing the
$base
variable in theexample/index.php
file; the browser you'll be testing from must be able to resolve the FQDN (the default ishttps://sp.example.com
). Using HTTPS is strongly suggested. -
Configure and install the test IdP spid-testenv2
-
Serve the
example
dir from your preferred webserver -
Visit https://sp.example.com/metadata to get the SP metadata, then copy these over to the IdP and register the SP with the IdP
-
Visit https://idp.example.com/metadata to get the IdP metadata, then save it as
example/idp_metadata/testenv.xml
to register the IdP with the SP -
Visit: https://sp.example.com and click
login
.
Demo application
A Docker-based demo application is available at https://github.com/simevo/spid-php-lib-example.
Features
- provides a lean implementation without relying on external SAML packages
- routing-agnostic, can be integrated in any web framework / CMS
- uses a session to store the authentication result and the received attributes
- does not currently support Attribute Authority (AA)
More features
- Generation of SPID button markup
Troubleshooting
It is advised to install a browser plugin to trace SAML messages:
-
Firefox:
-
Chrome/Chromium:
In addition, you can use the SAML Developer Tools provided by onelogin to understand what is going on
Testing
To test and lint this package you must place yourself in its root directory, then follow the provided instructions.
Assuming you followed the installation instructions with composer, simply do:
cd vendor/italia/spid-php-lib
Unit tests
Install prerequisites with composer, generate key and certificate for the SP and download the metadata for all current production IdPs with:
composer install bin/download_idp_metadata.php example/idp_metadata
then launch the unit tests with PHPunit:
./vendor/bin/phpunit --stderr --testdox tests
Linting
This project complies with the PSR-2: Coding Style Guide.
Make sure you are in the package directory, then lint the code with:
./vendor/bin/phpcs --standard=PSR2 xxx.php
Contributing
For your contributions please use the git-flow workflow.
See also
- SPID page on Developers Italia
Authors
Lorenzo Cattaneo and Paolo Greppi, simevo s.r.l.
License
Copyright (c) 2018-2020, Developers Italia
License: BSD 3-Clause, see LICENSE file.