simplesamlphp-errorhandling.md

Exception and error handling in SimpleSAMLphp

This document describes the way errors and exceptions are handled in authentication sources and authentication processing filters. The basic goal is to be able to throw an exception during authentication, and then have that exception transported back to the SP in a way that the SP understands.

This means that internal SimpleSAMLphp exceptions must be mapped to transport specific error codes for the various transports that are supported by SimpleSAMLphp. E.g.: When a \SimpleSAML\Error\NoPassive error is thrown by an authentication processing filter in a SAML 2.0 IdP, we want to map that exception to the urn:oasis:names:tc:SAML:2.0:status:NoPassive status code. That status code should then be returned to the SP.

Throwing exceptions

How you throw an exception depends on where you want to throw it from. The simplest case is if you want to throw it during the authenticate()-method in an authentication module or during the process()-method in a processing filter. In those methods, you can just throw an exception:

public function process(&$state) {
    if ($state['something'] === false) {
        throw new \SimpleSAML\Error\Exception('Something is wrong...');
    }
}

Exceptions thrown at this stage will be caught and delivered to the appropriate error handler.

If you want to throw an exception outside of those methods, i.e. after you have done a redirect, you need to use the \SimpleSAML\Auth\State::throwException() function:

<?php
$id = $_REQUEST['StateId'];
$state = \SimpleSAML\Auth\State::loadState($id, 'somestage...');
\SimpleSAML\Auth\State::throwException($state,
    new \SimpleSAML\Error\Exception('Something is wrong...'));
?>

The \SimpleSAML\Auth\State::throwException function will then transfer your exception to the appropriate error handler.