PHP / OneLogin

Requirements

The cookbook uses the OneLogin SAML2 library and requires PHP >= 7.3.

Runtime Example

Included in the repository is a dockerized application for hands-on learners. It starts an Identity Provider and one Service Provider per example.

Clone the Repository

git clone https://gitlab.code.rit.edu/systems-public/saml-cookbook.git

Start Containers

The examples requires docker and docker-compose to run. You can download these by following instructions from the official Docker website.

After dependencies have been installed, navigate to the ./saml-cookbook/docker folder in a terminal and run the following command.

# Get a coffee, this is going to take a while
docker-compose build && docker-compose up

You can now view the example at https://saml-cookbook.localtest.me/. If you’re having issues verify that the command completed without errors and that localhost:443 is forwarding traffic to your docker containers.

All the code can be found at ./saml-cookbook/docker/<example>/.

---

Integration and Pre-Requisites

Install the onelogin/php-saml library with composer and you’re good to go.

Extract IdP Settings

Find the IdP metadata. RIT’s IdP metadata can be found here.

You’ll need the entity id, the signing certificate, and the single sign-on service url. All the examples in this cookbook default to using RIT’s SAML IdP metadata.

Configuration

Note

If you’re confused about any of the terms, refer to the glossary.

Selecting an Entity Id

An entity id must be a URI you own. An example of a good entity id is $serviceUrl + /saml2, or the URL of your metadata.

Do not use bare words like widgets or URIs owned by other entities like google.com/widgets.

Create a Keypair

You will need a public and private keypair to encrypt and sign communication between the IdP and your service. You must generate a separate keypair every time you create a new entity id. Included is a one-line example to show how we could easily create a keypair for our service.

openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 \
    -keyout "service.key" -out "service.crt" -subj "/CN=widgets.rit.edu"

Create Your Settings

Refer to the official documentation for an expanded list of options.

Save this alongside your application or integrate it with an existing settings file. These settings configure how you send requests to the IdP and how you parse responses.

Modify the settings in the SP Section and IdP Section to get started.

Variable Settings

/** SP Section **/
// base url of your site
$baseUrl = 'https://widgets.rit.edu/';
// your generated entity id
$spEntityId = 'https://widgets.rit.edu/saml2';
// your generated keypair information
// base64 encoded certificate (PEM) for the SP
$spCert = file_get_contents('/abs/path/to/service.crt');
// base64 encoded private key (PEM) for the SP
$spKey = file_get_contents('/abs/path/to/service.key');
/** End SP Section **/

/** IdP Section **/
// The following fields will be supplied to you
// or extracted from metadata.

// entity id for your IdP
$idpEntityId = 'https://shibboleth.main.ad.rit.edu/idp/shibboleth';
// single-sign-on url for your IdP, defaults to Redirect binding
$idpSSOUrl = 'https://shibboleth.main.ad.rit.edu/idp/profile/SAML2/Redirect/SSO';

// base64 encoded certificate (PEM)
$idpCert = file_get_contents('/abs/path/to/idp.crt');
/** End IdP Section **/

Common Settings

return [
    'strict' => true,
    // Enable debug mode (to print errors).
    'debug' => false,
    'baseurl' => $baseUrl,
    'security' => array (
        'signMetadata' => true,
        /** signatures and encryptions required **/
        // Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest>
        // and <samlp:LogoutResponse> elements received by this SP to be signed.
        'wantMessagesSigned' => true,
        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be encrypted.
        'wantAssertionsEncrypted' => true,
        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be signed. [Metadata of the SP will offer this info]
        'wantAssertionsSigned' => true,
        'signatureAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
        'digestAlgorithm' => 'http://www.w3.org/2001/04/xmlenc#sha256',
        // Don't request an AuthnContext unless you know what you're doing,
        // the default AunthnContext is PasswordProtectedTransport, which is 
        // likely already what the IdP is doing.
        'requestedAuthnContext' => false
    ),
    // Service provider configuration.
    'sp' => array (
        // Identifier of the SP entity  (must be a URI)
        'entityId' => $spEntityId,
        // Specifies info about where and how the <AuthnResponse> message MUST be
        // returned to the requester, in this case our SP.
        'assertionConsumerService' => array (
            // URL Location where the <Response> from the IdP will be returned
            'url' => "{$baseUrl}/acs/",
            // SAML protocol binding to be used when returning the <Response>
            // message. SAML Toolkit supports this endpoint for the
            // HTTP-POST binding only.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
        ),
        // This is a x509 keypair generated specifically for this service
        'x509cert' => $spCert,
        'privateKey' => $spKey
    ),
    // Identity Provider Data that we want connected with our SP.
    'idp' => array (
        // Identifier of the IdP entity  (must be a URI)
        'entityId' => $idpEntityId,
        // SSO endpoint info of the IdP. (Authentication Request protocol)
        'singleSignOnService' => array (
            // URL Target of the IdP where the Authentication Request Message
            // will be sent.
            'url' => $idpSSOUrl,
            // SAML protocol binding to be used when returning the <Response>
            // message. SAML Toolkit supports the HTTP-Redirect binding
            // only for this endpoint.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        'x509cert' => $idpCert
    ),
];

Integrating SAML

Once your settings are taken care of you can begin integration. To integrate with a production IdP, you will need to exchange metadata and define the attributes you need for your service.

An example list of attributes you may need is:

• User name (uid)

• First name (givenName)

• Last name (sn)

• email (mail)

Generating Metadata

The IdP will require a copy of the metadata produced at this endpoint to register your service.

$auth = new OneLogin\Saml2\Auth($samlSettings);
$settings = $auth->getSettings();
$metadata = $settings->getSPMetadata();
header('Content-Type: text/xml');
echo $metadata;

Creating the AuthnRequest

The Auth::login function handles redirecting the user to the IdP with the correct parameters.

$auth = new OneLogin\Saml2\Auth($samlSettings);
$auth->login();

Parsing the Response from the IdP

The ACS endpoint extracts and operates on a payload set by the IdP. This is handled by the Auth::processResponse method. Any errors should be shown to the user and must prevent further processing of the request.

try {
    $auth = new OneLogin\Saml2\Auth($samlSettings);
    $auth->processResponse();
    $errors = $auth->getErrors();

    if (!empty($errors)) {
        echo '<p>' . htmlentities(implode(', ', $errors)) . '</p>';
        exit();
    }

    // Successful authentication, get attributes and create a very simple
    // session for the identity.
    $_SESSION['saml_identity'] = $auth->getAttributes();
    header('Location: /php/');
    exit();
}catch(Exception $exc){
    // Do not echo this directly to the client, this is only shown
    // for demonstration purposes. Convert the error to something
    // appropriate for the client and log this message.
    echo $exc->getMessage();
}

Extracting Attributes

After successfully parsing the IdP payload, the ACS can then extract attributes. These are returned as an associative array and may be mapped to an alias such as mail, uid, givenName or may use an oid such as 0.9.2342.19200300.100.1.1.

The above example includes processing attributes, and the relevant lines have been highlighted.

$auth->processResponse();
$errors = $auth->getErrors();

if (!empty($errors)) {
    echo '<p>' . htmlentities(implode(', ', $errors)) . '</p>';
    exit();
}

// Successful authentication, get attributes and create a very simple
// session for the identity.
$_SESSION['saml_identity'] = $auth->getAttributes();