php-saml

SAML PHP Toolkit

Add SAML support to your PHP software using this library.

The 3.X branch is compatible with PHP 7.0, PHP 7.1, PHP 7.2 , so if you are using that PHP version, use it and not the 2.X or the master branch

The 4.X branch is compatible with PHP >= 7.3 and PHP 8.X

Warning

Version 2.21.1 updates xmlseclibs to 3.1.4 due CVE-2025-66475

Version 2.18.0 introduces the 'rejectUnsolicitedResponsesWithInResponseTo' setting parameter, by default disabled, that will allow invalidate unsolicited SAMLResponse. This version as well will reject SAMLResponse if requestId was provided to the validator but the SAMLResponse does not contain a InResponseTo attribute. And an additional setting parameter 'destinationStrictlyMatches', by default disabled, that will force that the Destination URL should strictly match to the address that process the SAMLResponse.

Version 2.17.1 updates xmlseclibs to 3.0.4 (CVE-2019-3465), but php-saml was not directly affected since it implements additional checks that prevent to exploit that vulnerability.

Version 2.17.0 sets strict mode active by default

Update php-saml to 2.15.0, this version includes a security patch related to XEE attacks

php-saml is not affected by 201803-01

Update php-saml to 2.10.4, this version includes a security patch related to signature validations on LogoutRequests/LogoutResponses

Update php-saml to 2.10.0, this version includes a security patch that contains extra validations that will prevent signature wrapping attacks. CVE-2016-1000253

php-saml = 5.3.3and some core extensions likephp-xml, php-date, php-zlib`.

• openssl. Install the openssl library. It handles x509 certificates.
• mcrypt. Install that library and its php driver if you're going to handle encrypted data (nameID, assertions).
• curl. Install that library and its php driver if you plan to use the IdP Metadata parser.

Since PHP 5.3 is officially unsupported we recommend you to use a newer PHP version.

Code

Option 1. clone the repository from github

git clone [email protected]:onelogin/php-saml.git

Option 2. Download from github

The toolkit is hosted on github. You can download it from:

• Latest release: https://github.com/onelogin/php-saml/releases/latest
• Master repo: https://github.com/onelogin/php-saml/tree/master

Copy the core of the library inside the php application. (each application has its structure so take your time to locate the PHP SAML toolkit in the best place). See the "Guide to add SAML support to my app" to know how.

Take in mind that the compressed file only contains the main files. If you plan to play with the demos, use the Option 1.

Option 3. Composer

The toolkit supports composer. You can find the onelogin/php-saml package at https://packagist.org/packages/onelogin/php-saml

In order to import the saml toolkit to your current php project, execute

composer require onelogin/php-saml

After installation has completed you will find at the vendor/ folder a new folder named onelogin and inside the php-saml. Make sure you are including the autoloader provided by composer. It can be found at vendor/autoload.php.

Important In this option, the x509 certs must be stored at vendor/onelogin/php-saml/certs and settings file stored at vendor/onelogin/php-saml.

Your settings are at risk of being deleted when updating packages using composer update or similar commands. So it is highly recommended that instead of using settings files, you pass the settings as an array directly to the constructor (explained later in this document). If you do not use this approach your settings are at risk of being deleted when updating packages using composer update or similar commands.

Compatibility

This 2.0 version has a new library. The toolkit is still compatible.

The old code that you used in order to add SAML support will continue working with minor changes. You only need to load the files of the lib/Saml folder. (notice that the compatibility.php file do that).

The old-demo folder contains code from an old app that uses the old version of the toolkit (v.1). Take a look.

Sometimes the names of the classes of the old code could be a bit different and if that is your case you must change them for OneLogin_Saml_Settings, OneLogin_Saml_Response, OneLogin_Saml_AuthRequest or OneLogin_Saml_Metadata.

We recommend that you migrate the old code to the new one to be able to use the new features that the new library Saml2 carries.

Namespaces

If you are using the library with a framework like Symfony that contains namespaces, remember that calls to the class must be done by adding a backslash (\) to the start, for example to use the static method getSelfURLNoQuery use:

\OneLogin_Saml2_Utils::getSelfURLNoQuery()

Security warning

In production, the strict parameter MUST be set as "true" and the signatureAlgorithm and digestAlgorithm under security must be set to something other than SHA1 (see https://shattered.io/ ). Otherwise your environment is not secure and will be exposed to attacks.

In production also we highly recommended to register on the settings the IdP certificate instead of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism, we maintain it for compatibility and also to be used on test environment.

Avoiding Open Redirect attacks

Some implementations uses the RelayState parameter as a way to control the flow when SSO and SLO succeeded. So basically the user is redirected to the value of the RelayState.

If you are using Signature Validation on the HTTP-Redirect binding, you will have the RelayState value integrity covered, otherwise, and on HTTP-POST binding, you can't trust the RelayState so before executing the validation, you need to verify that its value belong a trusted and expected URL.

Read more about Open Redirect CWE-601.

Avoiding Replay attacks

A replay attack is basically try to reuse an intercepted valid SAML Message in order to impersonate a SAML action (SSO or SLO).

SAML Messages have a limited timelife (NotBefore, NotOnOrAfter) that make harder this kind of attacks, but they are still possible.

In order to avoid them, the SP can keep a list of SAML Messages or Assertion IDs already validated and processed. Those values only need to be stored the amount of time of the SAML Message life time, so we don't need to store all processed message/assertion Ids, but the most recent ones.

The OneLogin_Saml2_Auth class contains the getLastRequestID, getLastMessageId and getLastAssertionId methods to retrieve the IDs

Checking that the ID of the current Message/Assertion does not exists in the list of the ones already processed will prevent reply attacks.

Getting started

Knowing the toolkit

The new OneLogin SAML Toolkit contains different folders (certs, endpoints, extlib, lib, demo, etc.) and some files.

Let's start describing the folders:

certs/

SAML requires a x509 cert to sign and encrypt elements like NameID, Message, Assertion, Metadata.

If our environment requires sign or encrypt support, this folder may contain the x509 cert and the private key that the SP will use:

• sp.crt - The public cert of the SP
• sp.key - The private key of the SP

Or also we can provide those data in the setting file at the $settings['sp']['x509cert'] and the $settings['sp']['privateKey'].

Sometimes we could need a signature on the metadata published by the SP, in this case we could use the x509 cert previously mentioned or use a new x509 cert: metadata.crt and metadata.key.

Use sp_new.crt if you are in a key rollover process and you want to publish that x509 certificate on Service Provider metadata.

extlib/

This folder contains the 3rd party libraries that the toolkit uses. At the moment only uses the xmlseclibs (author Robert Richards, BSD Licensed) which handle the sign and the encryption of xml elements.

lib/

This folder contains the heart of the toolkit, the libraries:

• Saml folder contains a modified version of the toolkit v.1 and allows the old code to keep working. (This library is provided to maintain backward compatibility).
• Saml2 folder contains the new version of the classes and methods that are described in a later section.

doc/

This folder contains the API documentation of the toolkit.

endpoints/

The toolkit has three endpoints:

• metadata.php - Where the metadata of the SP is published.
• acs.php - Assertion Consumer Service. Processes the SAML Responses.
• sls.php - Single Logout Service. Processes Logout Requests and Logout Responses.

You can use the files provided by the toolkit or create your own endpoints files when adding SAML support to your applications. Take in mind that those endpoints files uses the setting file of the toolkit's base folder.

locale/

Locale folder contains some translations: en_US and es_ES as a proof of concept. Currently there are no translations but we will eventually localize the messages and support multiple languages.

Other important files

• settings_example.php - A template to be used in order to create a settings.php file which contains the basic configuration info of the toolkit.
• advanced_settings_example.php - A template to be used in order to create a advanced_settings.php file which contains extra configuration info related to the security, the contact person, and the organization associated to the SP.
• _toolkit_loader.php - This file load the toolkit libraries (The SAML2 lib).
• compatibility - Import that file to make compatible your old code with the new toolkit (loads the SAML library).

Miscellaneous

• tests/ - Contains the unit test of the toolkit.
• demo1/ - Contains an example of a simple PHP app with SAML support. Read the Readme.txt inside for more info.
• demo2/ - Contains another example.
• demo-old/ - Contains an example that uses the code of the older version of the the toolkit to demonstrate the backwards compatibility.

How it works

Settings

First of all we need to configure the toolkit. The SP's info, the IdP's info, and in some cases, configure advanced security issues like signatures and encryption.

There are two ways to provide the settings information:

• Use a settings.php file that we should locate at the base folder of the toolkit.
• Use an array with the setting data and provide it directly to the constructor of the class.

There is a template file, settings_example.php, so you can make a copy of this file, rename and edit it.

…

In addition to the required settings data (IdP, SP), there is extra information that could be defined. In the same way