⚠️ WORK IN PROGRESS⚠️
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.
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).
Alternatives for PHP:
- spid-php based on SimpleSAMLphp
- spid-php2 based on php-saml
Alternatives for other languages:
Repository layout
- bin/ auxiliary scripts
- example/ will contain a demo application
- src/ will contain the implementation
- test/ will contain the unit tests
Getting Started
Tested on: amd64 Debian 9.5 (stretch, current stable) with PHP 7.0.
Prerequisites
sudo apt install composer make openssl php-curl php-zip php-xml phpunit
Configuring and Installing
Before using this package, you must:
-
Install prerequisites with composer
-
Download and verify the Identity Provider (IdP) metadata files; it is advised to place them in a separate idp_metadata/ directory. A convenience tool is provided for this purpose: bin/download_idp_metadata.php.
-
Generate key and certificate for the Service Provider (SP).
All steps can be performed in an unattended fashion with:
composer install --no-dev
make
bin/download_idp_metadata.php ./example/idp_metadata
NOTE: during testing, it is highly adviced to use the test Identity Provider spid-testenv2.
Usage
All classes provided by this package reside in the Italia\Spid
namespace.
Load them using the composer-generated autoloader:
require_once(__DIR__ . "/../vendor/autoload.php");
The main class is Italia\Spid\Sp
(service provider), sample instantiation:
$settings = array(
'sp_entityid' => 'https://example.com/myservice',
'idp_metadata_folder' => './idp_metadata/',
...
);
$sp = new Italia\Spid\Sp($settings);
By default the the service provider loads all IdP metadata found in the specified idp_metadata_folder
and is ready for use, as in:
// shortname of IdP, same as the name of corresponding IdP metadata file, without .xml
$idpName = 'testenv';
// return url
$returnTo = 'https://example.com/return_to_url';
// index of assertion consumer service as per the SP metadata
$assertId = 0;
// index of attribute consuming service as per the SP metadata
$attrId = 1;
// SPID level (1, 2 or 3)
$spidLevel = 1;
$sp->login($idpName, $assertId, $attrId, $redirectTo, $spidLevel);
...
$attributes = $sp->getAttributes();
var_dump($attributes);
$sp->logout();
Example
A basic demo application is provided in the example/ directory.
To use:
- in
example/index.php
:
- adapt the base url (
$base
) to your needs (use am IP address or a FQDN that is visible to the IdP)
-
in
example/login.php
change the IdP that will be used to login -
Serve the
example
dir from your preferred webserver -
visit https://sp.example.com/metadata.php to get the SP (Service Provider) metadata, then copy these over to the IdP and register the SP
-
visit: https://sp.example.com and click
login
.
This screencast shows what you should see if all goes well:
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
Unit tests
Launch unit tests with PHPunit:
phpunit --stderr --testdox tests
Linting
This project complies with the PSR-2: Coding Style Guide.
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, Developers Italia
License: BSD 3-Clause, see LICENSE file.