Summary: Secure SAML Service Provider

Description: Secure SAML Service Provider with a focus on saml2int compatibility and easy integration in PHP applications.

License: MIT

Introduction

A SAML Service Provider (SP) with an easy API to use SAML authentication from your existing PHP applications.

This project received a comprehensive security audit by Cure53 in November 2020. The identified issues were fixed. You can read the audit report yourself.

Why

There are various options for integrating SAML in your PHP application. However, most are either (very) complicated, include too many (useless) features, have hard requirements on Apache and are not easy to package for server operating systems like CentOS/Fedora and/or Debian.

We only need SAML SP support, so there is no need to include any IdP features, or other (obsolete) authentication protocols.

In addition, we only implement what is actually used "in the field" and that which is secure. So you won't find SHA1 support or insecure encryption.

Features

Only SAML SP functionality
Only HTTP-Redirect for sending AuthnRequest, LogoutRequest to IdP
Only HTTP-Redirect binding for receiving LogoutResponse from IdP
Only HTTP-POST binding for receiving Response from IdP
Always signs AuthnRequest
Always signs LogoutRequest
Supports signed samlp:Response and/or signed samlp:Response/saml:Assertion
Supports multiple IdP certificates for key rollover
Allow specifying AuthnContextClassRef as part of the AuthnRequest
Serializes eduPersonTargetedID as idpEntityId!spEntityId!persistentId (like Shibboleth);
Only supports urn:oid SAML attributes from a list of allowed attributes, ignores the rest
Verify "scope" of attributes based on <shibmd:Scope> metadata element when the IdP metadata contains this element
- Silently removes the attribute (value) when scope does not match
Converts urn:oid attribute names to "friendly" names for use by applications
Supports automated metadata retrieval/update with XML schema / signature verification, see METADATA
Validates XML schema(s) when processing XML protocol messages
Tested with IdPs:
Simple built-in WAYF when more than 1 IdP is configured for the SP
Support external discovery services implementing Identity Provider Discovery Service Protocol and Profile

SAML V2.0 Deployment Profile for Federation Interoperability

We do aim to eventually support everything as mentioned in SAML V2.0 Deployment Profile for Federation Interoperability.

Cryptographic Algorithms

Type	Algorithm(s)	Supported
Digest	`http://www.w3.org/2001/04/xmlenc#sha256`	Yes
Signature	`http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`	Yes
	`http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256`	No
Block Encryption	`http://www.w3.org/2009/xmlenc11#aes128-gcm`	Yes
	`http://www.w3.org/2009/xmlenc11#aes256-gcm`	Yes
Key Transport	`http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p`	Yes
Key Transport Digest	`http://www.w3.org/2000/09/xmldsig#sha1`	Yes

Requirements

PHP >= 5.4
- For encryption (<EncryptedAssertion>) support, PHP >= 7.1
php-openssl
See composer.json for additional dependencies

Installation

See INSTALL for manual installation.

In the near future we'll provide supported CentOS/Fedora and Debian/Ubuntu packages.

Currently we have CentOS/Fedora packages in COPR.

Source Code Layout

The src/ directory contains the SAML SP implementation library. The directory src/Web contains everything related to the built-in web interface providing the landing page and WAYF. The src/Api directory contains everything related to the API to use from your PHP application.

Development

Run composer to install the dependencies:

$ /path/to/composer install

Use the following command to create self-signed certificates for use with the SP library. It will be used for signing the <AuthnRequest> and <LogoutRequest>. Another set will be used for decryption of <EncryptedAssertion>.

$ cd keys
$ ./generate_keys.sh

Now copy the configuration template:

$ cp config/config.php.example config/config.php

Disable the Secure session cookie parameter by setting the secureCookie key to false in config/config.php.

A neat IdP to use for testing is https://x509idp.moonshot.utr.surfcloud.nl/metadata. There's no need to register your SP with that IdP. Put the metadata in config/metadata:

$ mkdir config/metadata
$ curl -L -o config/metadata/x509idp.moonshot.utr.surfcloud.nl.xml https://x509idp.moonshot.utr.surfcloud.nl/metadata

Run the application using PHP's built-in web server:

$ php -S localhost:8082 -t web

With your browser you can go to http://localhost:8082/ and take it from there!

IdP Configuration

In case you want to add / configure your IdP to use with this software, make sure:

the IdP uses the HTTP-Redirect binding for receiving the AuthnRequest;
the IdP uses the HTTP-POST binding to provide the samlp:Response to the SP;
the IdP signs the saml:Assertion and/or the samlp:Response;
the IdP (optionally) encrypts the saml:Assertion;
the IdP verifies the signature on the samlp:AuthnRequest;
the IdP verifies the signature on the samlp:LogoutRequest;
the IdP signs the samlp:LogoutResponse.

Some of these requirements are also exposed through the SP metadata.

simpleSAMLphp

In your simpleSAMLphp's metadata/saml20-sp-remote.php file, configure this for this SP:

'validate.authnrequest' => true,
'sign.logout' => true,
'validate.logout' => true,

API

See API for how to use php-saml-sp from your PHP application.

Tests

In order to run the included test suite:

$ vendor/bin/phpunit

ezeasorekene / php-saml-sp