Download the PHP package italia/spid-php-lib without Composer

CURRENT VERSION: v0.35

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:

• spid-perl
• spid-ruby

Table of Contents

• spid-php-lib
• Table of Contents
  • Repository layout
  • Getting Started
  • PHP compatibility
  • Prerequisites
  • Configuring and Installing
  • Usage
    • Performing login
    • Performing logout
    • Complete API
  • Example
    • Demo application
  • Features
  • More features
  • Troubleshooting
  • Testing
  • Unit tests
  • Linting
  • Contributing
  • See also
  • Authors
  • License

Repository layout

• bin/ auxiliary scripts
• example/ contains a demo application
• src/ contains the library implementation
• test/ contains the unit tests

Getting Started

PHP compatibility

The constraint declared in composer.json is "php": "^7.4 || ^8.0", that is PHP 7.4 and every 8.x release. The table below reports what has actually been verified by running the whole CI pipeline (composer validate --strict, composer install, phpcs --standard=PSR2, phpunit) on each release, against the production IdP metadata downloaded from the SPID registry. End-of-life dates are the ones published on php.net/supported-versions and php.net/eol.

Notes:

• PHP 7.4, 8.0 and 8.1 have reached end of life upstream and receive no security fixes. They are kept in the matrix for backward compatibility only: new deployments should target PHP 8.4 or 8.5.
• No deprecation notice is emitted by the library on any of these releases. In particular every implicitly nullable parameter (Type $x = null, deprecated since 8.4 and an error in PHP 9.0) has been made explicit.

Prerequisites

Configuring and Installing

NOTE: during testing, please use the test Identity Provider spid-testenv2.

1. Install with composer

2. (OPTIONAL) Manually generate key and certificate files for your Service Provider (SP).

   Example:

   This step can be skipped: the library takes care of this step automatically if you declare the optional sp_key_cert_values key in the settings array. Check the example in the Usage section for further details.

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

   How the tool gets the metadata, and what that means for you. The SPID registry used to publish, for every IdP, the URL of the metadata document the IdP itself signs and serves; the tool downloaded that document verbatim. That endpoint is gone, and the registry no longer exposes a per-IdP metadata URL: it returns the entityID, the SSO/SLO endpoints and the signing certificates as JSON. The tool now rebuilds the metadata from that payload, which means the files it writes are not signed and are trusted on the strength of the TLS connection to registry.spid.gov.it alone. This library never verified the metadata signature anyway, so its own behaviour is unchanged — but if your deployment or your compliance process verifies the stored metadata against the AgID trust anchor, that check is no longer possible on these files and you should keep fetching each IdP's own document instead.

   The tool also writes only the signing certificates that are currently valid: the registry lists expired ones too, sometimes first, and this library reads only the first certificate of the document. Re-run the tool when a certificate is about to expire; it warns on stderr about any file in the destination directory that it did not write, which is what you get for an IdP that has left the registry, and for the files of an older version of the tool, whose naming scheme followed the old registry payload.

   TEST ENVIRONMENT: If you are using spid-testenv2, manually download the IdP metadata and place it in your idp_metadata folder

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

The main class is Italia\Spid\Sp (service provider).

Generate a settings array following this guideline

then initialize the main Sp class

Don't want the library to generate .key and .crt files for you? Then remove the sp_key_cert_values key from the settings array, or decalre

Performing login

Complete the login operation by calling

at the assertion consumer service URL.

Then call

to receive an array of the requested user attributes.

Performing logout

Call

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:

1. Generate a test certificate and key pair with:

2. Adapt the hostname of the SP changing the $base variable in the example/index.php file; the browser you'll be testing from must be able to resolve the FQDN (the default is https://sp.example.com). Using HTTPS is strongly suggested.

3. Configure and install the test IdP spid-testenv2

4. Serve the example dir from your preferred webserver

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

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

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

_Compliance with SPID regulations (for Service Providers)_
Metadata:
parsing of IdP XML metadata (1.2.2.4)	✓
support for multiple signing certificates in IdP XML metadata (1.2.2.4)
parsing of AA XML metadata (2.2.4)
SP XML metadata generation (1.3.2)	✓
AuthnRequest generation (1.2.2.1):
generation of AuthnRequest XML	✓
HTTP-Redirect binding	✓
HTTP-POST binding	✓
AssertionConsumerServiceURL customization	The library uses AssertionConsumerServiceIndex customization which is preferred
AssertionConsumerServiceIndex customization	✓
AttributeConsumingServiceIndex customization	✓
AuthnContextClassRef (SPID level) customization	✓
RequestedAuthnContext/@Comparison customization	✓
RelayState customization (1.2.2)	✓
Response/Assertion parsing
verification of Signature value (if any)	✓
verification of Signature certificate (if any) against IdP/AA metadata	✓
verification of Assertion/Signature value	✓
verification of Assertion/Signature certificate against IdP/AA metadata	✓
verification of SubjectConfirmationData/@Recipient	✓
verification of SubjectConfirmationData/@NotOnOrAfter	✓
verification of SubjectConfirmationData/@InResponseTo	✓
verification of Issuer	✓
verification of Assertion/Issuer	✓
verification of Destination	✓
verification of Conditions/@NotBefore	✓
verification of Conditions/@NotOnOrAfter	✓
verification of Audience	✓
parsing of Response with no Assertion (authentication/query failure)	✓
parsing of failure StatusCode (Requester/Responder)	✓
Response/Assertion parsing for SSO (1.2.1, 1.2.2.2, 1.3.1):
parsing of NameID	✓
parsing of AuthnContextClassRef (SPID level)	✓
parsing of attributes	✓
Response/Assertion parsing for attribute query (2.2.2.2, 2.3.1):
parsing of attributes
LogoutRequest generation (for SP-initiated logout):
generation of LogoutRequest XML	✓
HTTP-Redirect binding	✓
HTTP-POST binding	✓
LogoutResponse parsing (for SP-initiated logout):
parsing of LogoutResponse XML	✓
verification of Response/Signature value (if any)	✓
verification of Response/Signature certificate (if any) against IdP metadata	✓
verification of Issuer	✓
verification of Destination	✓
PartialLogout detection	pending, see: #46
LogoutRequest parsing (for third-party-initiated logout):
parsing of LogoutRequest XML	✓
verification of Response/Signature value (if any)	✓
verification of Response/Signature certificate (if any) against IdP metadata	✓
verification of Issuer	✓
verification of Destination	✓
parsing of NameID	✓
LogoutResponse generation (for third-party-initiated logout):
generation of LogoutResponse XML	✓
HTTP-Redirect binding	✓
HTTP-POST binding	✓
PartialLogout customization	pending, see: #46
AttributeQuery generation (2.2.2.1):
generation of AttributeQuery XML
SOAP binding (client)

More features

• [x] Generation of SPID button markup

Security requirements for integrators

Some of the security properties of a SPID login depend on the application around this library, not only on the library itself.

• Select the Identity Provider by name, from a server-side list. login() and loginPost() take the identifier of an IdP whose metadata is in idp_metadata_folder; the certificate in that metadata is the trust anchor used to validate the Response. The library resolves the identifier inside the configured folder and refuses paths, URLs and stream wrappers, but the application should still validate the value against getIdpList() before passing it on, as example/views/login.php does. Never pass a request parameter straight to login().
• Keep the metadata folder trustworthy. Every *.xml in it is a trust anchor. Only the IdP metadata your deployment has verified belongs there, and the directory should not be writable by the web server. bin/download_idp_metadata.php refreshes it from the SPID registry.
• Configure PHP sessions properly. The library regenerates the session id when the login completes, but the surrounding settings are the application's: session.use_strict_mode=1 and session.use_only_cookies=1, cookies marked Secure and HttpOnly with an explicit SameSite, and HTTPS throughout.
• Check the level you get. The level asserted by the IdP is validated against the one requested in the AuthnRequest, following RequestedAuthnContext/@Comparison (sp_comparison, exact by default). Read getAttributes() and the session level rather than assuming the requested level was honoured.
• Keep the dependencies current. robrichards/xmlseclibs must be at least 3.1.5. Update composer.lock too, not just composer.json, and run composer audit as part of your release.

Troubleshooting

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

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:

Unit tests

Install the prerequisites with composer:

then launch the unit tests with PHPunit:

The suite runs against the IdP metadata committed under tests/fixtures/idp_metadata/, so it needs no network access and its result does not depend on the SPID registry being reachable. To exercise the registry itself, run the downloader by hand:

which is what the nightly registry-smoke CI job does.

Linting

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

Make sure you are in the package directory, then lint the code with:

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.