PHP / OneLogin
==================

.. contents:: Table of Contents
    :local:
    :depth: 3
    

Requirements
------------

The cookbook uses the `OneLogin SAML2 library <https://github.com/SAML-Toolkits/php-saml>`_ and requires PHP >= 7.3.

.. include:: /includes/runtime-example.rstinc

----------------

Integration and Pre-Requisites
------------------------------

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

Extract IdP Settings
^^^^^^^^^^^^^^^^^^^^

.. include:: /includes/extract-idp-settings.rstinc


Configuration
-------------

.. note:: 
    If you're confused about any of the terms, refer to the :ref:`glossary <Glossary>`.

Selecting an Entity Id
^^^^^^^^^^^^^^^^^^^^^^

.. include:: /includes/selecting-entityid.rstinc 

Create a Keypair
^^^^^^^^^^^^^^^^

.. include:: /includes/creating-keypair.rstinc

Create Your Settings
^^^^^^^^^^^^^^^^^^^^

`Refer to the official documentation for an expanded list of options <https://github.com/SAML-Toolkits/php-saml/blob/master/settings_example.php>`_. 

Save this alongside your application or integrate it with an existing settings file. These settings configure
how you send requests to the :term:`IdP <Identity Provider>` and how you parse responses.

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

.. code-block:: php
    :linenos:
    :caption: 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 **/

.. literalinclude:: ../../../docker/php/var/www/php/src/samlSettings.php
    :start-after: /* settings example */
    :end-before: /* end settings example */
    :language: php
    :linenos:
    :dedent: 
    :caption: Common Settings

Integrating SAML
----------------

.. include:: /includes/integrating-acs.rstinc

Generating Metadata
^^^^^^^^^^^^^^^^^^^

The :term:`IdP<Identity Provider>` will require a copy of the :term:`metadata<Metadata>` produced at this endpoint to register your service.

.. literalinclude:: ../../../docker/php/var/www/php/src/app.php 
    :start-after: /* metadata example */
    :end-before: /* end metadata example */
    :language: php
    :linenos:
    :dedent:

Creating the AuthnRequest
^^^^^^^^^^^^^^^^^^^^^^^^^

The ``Auth::login`` function handles redirecting the user to the :term:`IdP <Identity Provider>` with the correct parameters.

.. literalinclude:: ../../../docker/php/var/www/php/src/app.php
    :start-after: /* login example */
    :end-before: /* end login example */
    :language: php
    :linenos:
    :dedent:


Parsing the Response from the IdP
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

.. literalinclude:: ../../../docker/php/var/www/php/src/app.php
    :start-after: /* acs example */
    :end-before: /* end acs example */
    :language: php
    :linenos:
    :dedent: 

Extracting Attributes
^^^^^^^^^^^^^^^^^^^^^

After successfully parsing the :term:`IdP<Identity Provider>` payload, the :term:`ACS<ACS Endpoint>` 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.

.. literalinclude:: ../../../docker/php/var/www/php/src/app.php
    :start-at: processResponse
    :end-at: getAttributes
    :emphasize-lines: 1,11
    :language: php
    :linenos:
    :dedent: