⚠️ REPOSITORY NON PIÙ MANTENUTO. PER UNA VERSIONE AGGIORNATA DELLA LIBRERIA VEDERE italia/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:

• spid-perl
• spid-ruby

• bin/ auxiliary scripts
• example/ will contain a demo application
• src/ will contain the implementation
• test/ will contain the unit tests

Tested on: amd64 Debian 9.5 (stretch, current stable) with PHP 7.0.

sudo apt install composer make openssl php-curl php-zip php-xml phpunit

Before using this package, you must:

1. Install prerequisites with composer

2. 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.

3. 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

NOTE: during testing, it is highly adviced to use the test Identity Provider spid-testenv2.

All classes provided by this package reside in the Italia\Spid3 namespace.

Load them using the composer-generated autoloader:

require_once(__DIR__ . "/../vendor/autoload.php");

The main class is Italia\Spid3\Sp (service provider), sample instantiation:

$settings = array(
    'sp_entityid' => 'https://example.com/myservice',
    'idp_metadata_folder' => './idp_metadata/',
    ...
);
$sp = new Italia\Spid3\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();

A basic demo application is provided in the example/ directory.

To use:

1. 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)

2. in example/login.php change the IdP that will be used to login

3. Serve the example dir from your preferred webserver

4. 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

5. visit: https://sp.example.com and click login.

This screencast shows what you should see if all goes well:

It is advised to install a browser plugin to trace SAML messages:

• Firefox:

  • SAML-tracer by Olav Morken, Jaime Perez
  • SAML Message Decoder by Magnus Suther

• Chrome/Chromium:

  • SAML Message Decoder by Magnus Suther
  • SAML Chrome Panel by MLai
  • SAML DevTools extension by stefan.rasmusson.as

In addition, you can use the SAML Developer Tools provided by onelogin to understand what is going on

Launch unit tests with PHPunit:

phpunit --testdox tests

This project complies with the PSR-2: Coding Style Guide.

Lint the code with:

./vendor/bin/phpcs --standard=PSR2 xxx.php

For your contributions please use the git-flow workflow.

• SPID page on Developers Italia

Lorenzo Cattaneo and Paolo Greppi.

Copyright (c) 2018, simevo s.r.l.

License: BSD 3-Clause, see LICENSE file.