PHPackages intervieweb/spid-php-lib - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. intervieweb/spid-php-lib ActiveLibrary[Authentication & Authorization](/categories/authentication) intervieweb/spid-php-lib ======================== PHP package for SPID authentication v1.0.5(1y ago)11.1k—0%BSD-3-ClausePHPPHP ^7.1 || ^8.0 Since Oct 20Pushed 1y agoCompare [ Source](https://github.com/intervieweb/spid-php-lib)[ Packagist](https://packagist.org/packages/intervieweb/spid-php-lib)[ RSS](/packages/intervieweb-spid-php-lib/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (6)Dependencies (5)Versions (10)Used By (0) Notice: Unofficial Release ========================== [](#notice-unofficial-release) Main differences with official release: - implements logging - uses PSR-12 style guide spid-php-lib ============ [](#spid-php-lib) PHP package for SPID authentication. This PHP package is aimed at implementing SPID **Service Providers**. [SPID](https://www.spid.gov.it/) 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](https://github.com/italia/spid-php) based on [SimpleSAMLphp](https://simplesamlphp.org/) - [spid-php2](https://github.com/simevo/spid-php2) based on [php-saml](https://github.com/onelogin/php-saml) Framework specific libraries and examples based on spid-php-lib: - - - Alternatives for other languages: - [spid-perl](https://github.com/italia/spid-perl) - [spid-ruby](https://github.com/italia/spid-ruby) Table of Contents ================= [](#table-of-contents) - [spid-php-lib](#spid-php-lib) - [Table of Contents](#table-of-contents) - [Repository layout](#repository-layout) - [Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Configuring and Installing](#configuring-and-installing) - [Usage](#usage) - [Performing login](#performing-login) - [Performing logout](#performing-logout) - [Complete API](#complete-api) - [Example](#example) - [Demo application](#demo-application) - [Features](#features) - [More features](#more-features) - [Troubleshooting](#troubleshooting) - [Testing](#testing) - [Unit tests](#unit-tests) - [Linting](#linting) - [Contributing](#contributing) - [See also](#see-also) - [Authors](#authors) - [License](#license) Repository layout ----------------- [](#repository-layout) - [bin/](bin/) auxiliary scripts - [example/](example/) contains a demo application - [src/](src/) contains the library implementation - [test/](test/) contains the unit tests Getting Started --------------- [](#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 [](#prerequisites) ``` sudo apt install composer make openssl php-curl php-zip php-xml ``` ### Configuring and Installing [](#configuring-and-installing) **NOTE**: during testing, please use the test Identity Provider [spid-testenv2](https://github.com/italia/spid-testenv2). 1. Install with composer `composer require italia/spid-php-lib` 2. (**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 the `settings` array. Check the example in the [Usage](#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](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](https://github.com/italia/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 *TEST ENVIRONMENT: simply download your Service Provider (SP) metadata and place it in the appropriate folder of the [test environment](https://github.com/italia/spid-testenv2). The test environment must be restarted after every change to the SP metadata.* ### Usage [](#usage) All classes provided by this package reside in the `Italia\Spid` namespace. More detailed documentation is available in the [SAMLInterface.php](/src/Spid/Interfaces/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 the `settings` array, or decalre* ``` // $autoconfiguration skips .key/.crt generation if set to false $sp = new Italia\Spid\Sp($settings, null, $autoconfiguration = false); ``` #### Performing login [](#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 [](#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 [](#complete-api) **Method****Description**\_\_contruct($settings, $protocol = null, $autoconfigure = true)`$settings` should be based on the example provided in the [Usage](#usage) section. `$protocol` represents the protocol used for login. At the moment only `SAML` is supported, and can be selected by either `$protocol = 'saml'` or the default `$protocol = null`. `$autoconfigure` tells the constructor if it should check for .key and .crt files at the specified location from the `$settings` array and generate them in case they are not found. Set this to `false` if you wish to generate those manually.loadIdpFromFile(string $filename)loads an `Idp` object by parsing the provided XML at `$filename`getIdpList() : arrayloads all the `Idp` objects from the `idp_metadata_folder` provided in settingsgetIdp(string $filename)alias of `loadIdpFromFile`getSPMetadata() : stringreturns the SP metadata as a stringlogin(string $idpFilename, int $assertID, int $attrID, $level = 1, string $redirectTo = null, $shouldRedirect = true)login with REDIRECT binding. Use `$idpFilename` to select in IdP for login by indicating the name (without extension) of an XML file in your `idp_metadata_folder`. `$assertID` and `$attrID` indicate respectively the array index of `sp_assertionconsumerservice` and `sp_attributeconsumingservice` provided in settings. Optional parameters: `$level` for SPID authentication level (1, 2 or 3), `$redirectTo` to indicate an url to redirect to after login, `$shouldRedirect` to indicate if the login function should automatically redirect to the IdP or should return the login url as a stringloginPost(string $idpName, int $ass, int $attr, $level = 1, string $redirectTo = null, $shouldRedirect = true)like login, but uses POST bindinglogout(int $slo, string $redirectTo = null, $shouldRedirect = true)logout with REDIRECT binding. `$slo` indicates the array index of the `sp_singlelogoutservice` provided in settings. Optional parameters: `$redirectTo` to indicate an url to redirect to after login, `$shouldRedirect` to indicate if the login function should automatically redirect to the IdP or should return the login url as a stringlogoutPost(int $slo, string $redirectTo = null, $shouldRedirect = true)like logout, but uses POST bindingisAuthenticated() : boolchecks if the user is authenticated. This method **MUST** be called after login and logout to finalize the operation.getAttributes() : arrayIf you requested attributes with an attribute consuming service during login, this method will return them in array format### Example [](#example) A basic demo application is provided in the [example/](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: ``` 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 ``` 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](https://github.com/italia/spid-testenv2) 4. Serve the `example` dir from your preferred webserver 5. Visit to get the SP metadata, then copy these over to the IdP and register the SP with the IdP 6. Visit to get the IdP metadata, then save it as `example/idp_metadata/testenv.xml` to register the IdP with the SP 7. Visit: and click `login`. #### Demo application [](#demo-application) A Docker-based demo application is available at . Features -------- [](#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) [![](https://github.com/italia/spid-graphics/raw/master/spid-logos/spid-logo-c-lb.png?raw=true)](https://github.com/italia/spid-graphics/blob/master/spid-logos/spid-logo-c-lb.png?raw=true) *Compliance with [SPID regulations](http://www.agid.gov.it/sites/default/files/circolari/spid-regole_tecniche_v1.pdf) (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` customizationThe 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 detectionpending, see: [\#46](https://github.com/italia/spid-php-lib/issues/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 customizationpending, see: [\#46](https://github.com/italia/spid-php-lib/issues/46)**AttributeQuery generation (2.2.2.1):**generation of AttributeQuery XMLSOAP binding (client)### More features [](#more-features) - Generation of SPID button markup Troubleshooting --------------- [](#troubleshooting) It is advised to install a browser plugin to trace SAML messages: - Firefox: - [SAML-tracer by Olav Morken, Jaime Perez](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) - [SAML Message Decoder by Magnus Suther](https://addons.mozilla.org/en-US/firefox/addon/saml-message-decoder-extension/) - Chrome/Chromium: - [SAML Message Decoder by Magnus Suther](https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm) - [SAML Chrome Panel by MLai](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace) - [SAML DevTools extension by stefan.rasmusson.as](https://chrome.google.com/webstore/detail/saml-devtools-extension/jndllhgbinhiiddokbeoeepbppdnhhio) In addition, you can use the [SAML Developer Tools](https://www.samltool.com/online_tools.php) provided by onelogin to understand what is going on Testing ------- [](#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 [](#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 [](#linting) This project complies with the [PSR-2: Coding Style Guide](https://www.php-fig.org/psr/psr-2/). Make sure you are in the package directory, then lint the code with: ``` ./vendor/bin/phpcs --standard=PSR2 xxx.php ``` Contributing ------------ [](#contributing) For your contributions please use the [git-flow workflow](https://danielkummer.github.io/git-flow-cheatsheet/). See also -------- [](#see-also) - [SPID page](https://developers.italia.it/it/spid) on Developers Italia Authors ------- [](#authors) Lorenzo Cattaneo and Paolo Greppi, simevo s.r.l. License ------- [](#license) Copyright (c) 2018-2020, Developers Italia License: BSD 3-Clause, see [LICENSE](LICENSE) file. ### Health Score 33 — LowBetter than 75% of packages Maintenance38 Infrequent updates — may be unmaintained Popularity19 Limited adoption so far Community13 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor3 3 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~82 days Recently: every ~99 days Total 6 Last Release 531d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/82217edf274c8c872d3b86cc1472d79115d44763eaed0b7e649cc08773f63c48?d=identicon)[Fylax](/maintainers/Fylax) --- Top Contributors [![simevo](https://avatars.githubusercontent.com/u/8254819?v=4)](https://github.com/simevo "simevo (11 commits)")[![Fylax](https://avatars.githubusercontent.com/u/6639528?v=4)](https://github.com/Fylax "Fylax (6 commits)")[![marcoalbarelli](https://avatars.githubusercontent.com/u/789508?v=4)](https://github.com/marcoalbarelli "marcoalbarelli (5 commits)")[![alranel](https://avatars.githubusercontent.com/u/594957?v=4)](https://github.com/alranel "alranel (4 commits)")[![justADevOps](https://avatars.githubusercontent.com/u/107627777?v=4)](https://github.com/justADevOps "justADevOps (4 commits)")[![lussoluca](https://avatars.githubusercontent.com/u/436670?v=4)](https://github.com/lussoluca "lussoluca (2 commits)")[![lorenzocattaneo](https://avatars.githubusercontent.com/u/22037356?v=4)](https://github.com/lorenzocattaneo "lorenzocattaneo (2 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (1 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/intervieweb-spid-php-lib/health.svg) ``` [![Health](https://phpackages.com/badges/intervieweb-spid-php-lib/health.svg)](https://phpackages.com/packages/intervieweb-spid-php-lib) ``` ### Alternatives [google/auth Google Auth Library for PHP 1.4k272.7M162](/packages/google-auth)[simplesamlphp/simplesamlphp A PHP implementation of a SAML 2.0 service provider and identity provider. 1.1k12.4M193](/packages/simplesamlphp-simplesamlphp)[litesaml/lightsaml SAML 2.0 PHP library 1055.5M18](/packages/litesaml-lightsaml)[simplesamlphp/saml2 SAML2 PHP library from SimpleSAMLphp 30317.2M40](/packages/simplesamlphp-saml2)[web-auth/webauthn-lib FIDO2/Webauthn Support For PHP 1225.3M72](/packages/web-auth-webauthn-lib)[web-auth/webauthn-framework FIDO2/Webauthn library for PHP and Symfony Bundle. 50570.7k1](/packages/web-auth-webauthn-framework) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)