Skip to content

Latest commit

 

History

History
85 lines (64 loc) · 3.94 KB

README.md

File metadata and controls

85 lines (64 loc) · 3.94 KB
Raw

SimpleSAMLphp SAML2 library

[Build Status] (https://travis-ci.org/simplesamlphp/saml2) [Coverage Status] (https://coveralls.io/r/simplesamlphp/saml2)

A PHP library for SAML2 related functionality. Extracted from SimpleSAMLphp, used by OpenConext. This library started as a collaboration between UNINETT and SURFnet but everyone is invited to contribute.

Before you use it

DO NOT USE THIS LIBRARY UNLESS YOU ARE INTIMATELY FAMILIAR WITH THE SAML2 SPECIFICATION.

If you are not familiar with the SAML2 specification and are simply looking to connect your application using SAML2, you should probably use SimpleSAMLphp.

While this library is tagged as stable it is currently not very developer friendly and its API is likely to change significantly in the future. It is however a starting point for collaboration between parties. So let us know what you would like to see in a PHP SAML2 library.

Note that the HTTP Artifact Binding and SOAP client do not work outside of SimpleSAMLphp.

Which version to pick?

It is strongly recommended to use the latest stable version of the 2.x range as that is the currently supported version.

The 1.x range should be considered deprecated. This means it will receive fixes and, if required, functionality may be backported. This version should only be relied on if migrating the project to the 2.x range cannot be done yet.

The 0.x range is discontinued and will no longer receive any fixes or features. The 0.x range however is functionally the same as the 1.x range. Should your project or a dependency of your project rely on a 0.x version composer inline aliasing will help, by using composer require "simplesamlphp/saml2:1.7.0 as 0.8" allows to install 1.7.0 as if 0.8 were installed.

Usage

  • Install with Composer, run the following command in your project:
composer require simplesamlphp/saml2:^2.0

  • Provide the required external dependencies by extending and implementing the SAML2\Compat\AbstractContainer then injecting it in the ContainerSingleton (see example below).

  • Make sure you've read the security section below

  • Use at will. Example:

    // Use Composers autoloading
    require 'vendor/autoload.php';

    // Implement the Container interface (out of scope for example)
    require 'container.php';
    SAML2\Compat\ContainerSingleton::setContainer($container);

    // Set up an AuthnRequest
    $request = new SAML2\AuthnRequest();
    $request->setId($container->generateId());
    $request->setIssuer('https://sp.example.edu');
    $request->setDestination('https://idp.example.edu');

    // Send it off using the HTTP-Redirect binding
    $binding = new SAML2\HTTPRedirect();
    $binding->send($request);

Security

  • Should you need to create a DOMDocument instance, use the SAML2\DOMDocumentFactory to create DOMDocuments from either a string (SAML2\DOMDocumentFactory::fromString($theXmlAsString)), a file (SAML2\DOMDocumentFactory::fromFile($pathToTheFile)) or just a new instance (SAML2\DOMDocumentFactory::create()). This in order to protect yourself against the XXE Processing Vulnerability, as well as XML Entity Expansion attacks

License

This library is licensed under the LGPL license version 2.1. For more details see LICENSE.