SimpleSAML_Auth_State Class Reference

Collaboration diagram for SimpleSAML_Auth_State:

Static Public Member Functions
static	getPersistentAuthData (array $state)
	Get the persistent authentication state from the state array. More...
static	getStateId (&$state, $rawId=false)
	Retrieve the ID of a state array. More...
static	saveState (&$state, $stage, $rawId=false)
	Save the state. More...
static	cloneState (array $state)
	Clone the state. More...
static	loadState ($id, $stage, $allowMissing=false)
	Retrieve saved state. More...
static	deleteState (&$state)
	Delete state. More...
static	throwException ($state, SimpleSAML_Error_Exception $exception)
	Throw exception to the state exception handler. More...
static	loadExceptionState ($id=null)
	Retrieve an exception state. More...
static	parseStateID ($stateId)
	Get the ID and (optionally) a URL embedded in a StateID, in the form 'id:url'. More...

Data Fields
const	ID = 'SimpleSAML_Auth_State.id'
	The index in the state array which contains the identifier. More...
const	CLONE_ORIGINAL_ID = 'SimpleSAML_Auth_State.cloneOriginalId'
	The index in the cloned state array which contains the identifier of the original state. More...
const	STAGE = 'SimpleSAML_Auth_State.stage'
	The index in the state array which contains the current stage. More...
const	RESTART = 'SimpleSAML_Auth_State.restartURL'
	The index in the state array which contains the restart URL. More...
const	EXCEPTION_HANDLER_URL = 'SimpleSAML_Auth_State.exceptionURL'
	The index in the state array which contains the exception handler URL. More...
const	EXCEPTION_HANDLER_FUNC = 'SimpleSAML_Auth_State.exceptionFunc'
	The index in the state array which contains the exception handler function. More...
const	EXCEPTION_DATA = 'SimpleSAML_Auth_State.exceptionData'
	The index in the state array which contains the exception data. More...
const	EXCEPTION_STAGE = 'SimpleSAML_Auth_State.exceptionStage'
	The stage of a state with an exception. More...
const	EXCEPTION_PARAM = 'SimpleSAML_Auth_State_exceptionId'
	The URL parameter which contains the exception state id. More...

Static Private Member Functions
static	getStateTimeout ()
	Retrieve state timeout. More...

Static Private Attributes
static	$stateTimeout = null
	State timeout. More...

Detailed Description

Definition at line 31 of file State.php.

Member Function Documentation

cloneState()

static SimpleSAML_Auth_State::cloneState ( array  $state )

static

Clone the state.

This function clones and returns the new cloned state.

Parameters

array

$state

The original request state.

Returns

array Cloned state data.

Definition at line 226 of file State.php.

References $state, and SimpleSAML\Logger\debug().

    {
        $clonedState = $state;

        if (array_key_exists(self::ID, $state)) {
            $clonedState[self::CLONE_ORIGINAL_ID] = $state[self::ID];
            unset($clonedState[self::ID]);

            SimpleSAML\Logger::debug('Cloned state: '.var_export($state[self::ID], true));
        } else {
            SimpleSAML\Logger::debug('Cloned state with undefined id.');
        }

        return $clonedState;
    }

Here is the call graph for this function:

deleteState()

static SimpleSAML_Auth_State::deleteState ( &  $state )

static

Delete state.

This function deletes the given state to prevent the user from reusing it later.

Parameters

array

&$state

The state which should be deleted.

Definition at line 319 of file State.php.

Referenced by SimpleSAML_Auth_Source\completeAuth(), SimpleSAML_Auth_Source\completeLogout(), sspmod_cas_Auth_Source_CAS\logout(), and SimpleSAML_Auth_ProcessingChain\resumeProcessing().

    {
        assert('is_array($state)');

        if (!array_key_exists(self::ID, $state)) {
            // This state hasn't been saved
            return;
        }

        SimpleSAML\Logger::debug('Deleting state: '.var_export($state[self::ID], true));

        $session = SimpleSAML_Session::getSessionFromRequest();
        $session->deleteData('SimpleSAML_Auth_State', $state[self::ID]);
    }

Here is the caller graph for this function:

getPersistentAuthData()

static SimpleSAML_Auth_State::getPersistentAuthData ( array  $state )

static

Get the persistent authentication state from the state array.

Parameters

array

$state

The state array to analyze.

Returns

array The persistent authentication state.

Definition at line 103 of file State.php.

References $key, and array.

Referenced by SimpleSAML_Auth_Default\extractPersistentAuthState(), sspmod_saml_Auth_Source_SP\handleUnsolicitedAuth(), SimpleSAML_Auth_Source\loginCompleted(), and sspmod_saml_Auth_Source_SP\reauthPostLogin().

    {
        // save persistent authentication data
        $persistent = array();

        if (array_key_exists('PersistentAuthData', $state)) {
            foreach ($state['PersistentAuthData'] as $key) {
                if (isset($state[$key])) {
                    $persistent[$key] = $state[$key];
                }
            }
        }

        // add those that should always be included
        $mandatory = array(
            'Attributes',
            'Expire',
            'LogoutState',
            'AuthInstant',
            'RememberMe',
            'saml:sp:NameID'
        );
        foreach ($mandatory as $key) {
            if (isset($state[$key])) {
                $persistent[$key] = $state[$key];
            }
        }

        return $persistent;
    }

Here is the caller graph for this function:

getStateId()

static SimpleSAML_Auth_State::getStateId ( &  $state,   $rawId = false  )

static

Retrieve the ID of a state array.

Note that this function will not save the state.

Parameters

array	&$state	The state array.
bool	$rawId	Return a raw ID, without a restart URL. Defaults to FALSE.

Returns

string Identifier which can be used to retrieve the state later.

Definition at line 145 of file State.php.

References $id, $state, and SimpleSAML\Utils\Random\generateID().

Referenced by sspmod_authlinkedin_Auth_Source_LinkedIn\authenticate(), and sspmod_authfacebook_Facebook\establishCSRFTokenState().

    {
        assert('is_array($state)');
        assert('is_bool($rawId)');

        if (!array_key_exists(self::ID, $state)) {
            $state[self::ID] = SimpleSAML\Utils\Random::generateID();
        }

        $id = $state[self::ID];

        if ($rawId || !array_key_exists(self::RESTART, $state)) {
            // Either raw ID or no restart URL. In any case, return the raw ID.
            return $id;
        }

        // We have a restart URL. Return the ID with that URL.
        return $id.':'.$state[self::RESTART];
    }

Here is the call graph for this function:

Here is the caller graph for this function:

getStateTimeout()

static SimpleSAML_Auth_State::getStateTimeout ( )

staticprivate

Retrieve state timeout.

Returns

integer State timeout.

Definition at line 171 of file State.php.

References $globalConfig, and SimpleSAML_Configuration\getInstance().

    {
        if (self::$stateTimeout === null) {
            $globalConfig = SimpleSAML_Configuration::getInstance();
            self::$stateTimeout = $globalConfig->getInteger('session.state.timeout', 60 * 60);
        }

        return self::$stateTimeout;
    }

Here is the call graph for this function:

loadExceptionState()

static SimpleSAML_Auth_State::loadExceptionState (   $id = null )

static

Retrieve an exception state.

Parameters

string | NULL

$id

The exception id. Can be NULL, in which case it will be retrieved from the request.

Returns

array|NULL The state array with the exception, or NULL if no exception was thrown.

Definition at line 381 of file State.php.

References $id, and $state.

    {
        assert('is_string($id) || is_null($id)');

        if ($id === null) {
            if (!array_key_exists(self::EXCEPTION_PARAM, $_REQUEST)) {
                // No exception
                return null;
            }
            $id = $_REQUEST[self::EXCEPTION_PARAM];
        }

        $state = self::loadState($id, self::EXCEPTION_STAGE);
        assert('array_key_exists(self::EXCEPTION_DATA, $state)');

        return $state;
    }

loadState()

static SimpleSAML_Auth_State::loadState (   $id,   $stage,   $allowMissing = false  )

static

Retrieve saved state.

This function retrieves saved state information. If the state information has been lost, it will attempt to restart the request by calling the restart URL which is embedded in the state information. If there is no restart information available, an exception will be thrown.

Parameters

string	$id	State identifier (with embedded restart information).
string	$stage	The stage the state should have been saved in.
bool	$allowMissing	Whether to allow the state to be missing.

Exceptions

SimpleSAML_Error_NoState	If we couldn't find the state and there's no URL defined to redirect to.
Exception	If the stage of the state is invalid and there's no URL defined to redirect to.

Returns

array|NULL State information, or null if the state is missing and $allowMissing is true.

Definition at line 259 of file State.php.

References $id, $session, $state, SimpleSAML\Logger\debug(), SimpleSAML_Session\getSessionFromRequest(), and SimpleSAML\Utils\HTTP\redirectUntrustedURL().

Referenced by SimpleSAML_Auth_ProcessingChain\fetchProcessedState(), sspmod_authYubiKey_Auth_Source_YubiKey\handleLogin(), sspmod_core_Auth_UserPassOrgBase\handleLogin(), sspmod_core_Auth_UserPassBase\handleLogin(), sspmod_core_Auth_UserPassOrgBase\listOrganizations(), SimpleSAML\IdP\TraditionalLogoutHandler\onResponse(), and sspmod_exampleauth_Auth_Source_External\resume().

    {
        assert('is_string($id)');
        assert('is_string($stage)');
        assert('is_bool($allowMissing)');
        SimpleSAML\Logger::debug('Loading state: '.var_export($id, true));

        $sid = self::parseStateID($id);

        $session = SimpleSAML_Session::getSessionFromRequest();
        $state = $session->getData('SimpleSAML_Auth_State', $sid['id']);

        if ($state === null) {
            // Could not find saved data
            if ($allowMissing) {
                return null;
            }

            if ($sid['url'] === null) {
                throw new SimpleSAML_Error_NoState();
            }

            \SimpleSAML\Utils\HTTP::redirectUntrustedURL($sid['url']);
        }

        $state = unserialize($state);
        assert('is_array($state)');
        assert('array_key_exists(self::ID, $state)');
        assert('array_key_exists(self::STAGE, $state)');

        // Verify stage
        if ($state[self::STAGE] !== $stage) {
            /* This could be a user trying to bypass security, but most likely it is just
             * someone using the back-button in the browser. We try to restart the
             * request if that is possible. If not, show an error.
             */

            $msg = 'Wrong stage in state. Was \''.$state[self::STAGE].
                '\', should be \''.$stage.'\'.';

            SimpleSAML\Logger::warning($msg);

            if ($sid['url'] === null) {
                throw new Exception($msg);
            }

            \SimpleSAML\Utils\HTTP::redirectUntrustedURL($sid['url']);
        }

        return $state;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

parseStateID()

static SimpleSAML_Auth_State::parseStateID (   $stateId )

static

Get the ID and (optionally) a URL embedded in a StateID, in the form 'id:url'.

Parameters

string

$stateId

The state ID to use.

Returns

array A hashed array with the ID and the URL (if any), in the 'id' and 'url' keys, respectively. If there's no URL in the input parameter, NULL will be returned as the value for the 'url' key.

Author

Andreas Solberg, UNINETT AS andre.nosp@m.as.s.nosp@m.olber.nosp@m.g@un.nosp@m.inett.nosp@m..no

Jaime Perez, UNINETT AS jaime.nosp@m..per.nosp@m.ez@un.nosp@m.inet.nosp@m.t.no

Definition at line 411 of file State.php.

References $id, $stateId, $url, and array.

Referenced by SimpleSAML_Utilities\parseStateID().

    {
        $tmp = explode(':', $stateId, 2);
        $id = $tmp[0];
        $url = null;
        if (count($tmp) === 2) {
            $url = $tmp[1];
        }
        return array('id' => $id, 'url' => $url);
    }

Here is the caller graph for this function:

saveState()

static SimpleSAML_Auth_State::saveState ( &  $state,   $stage,   $rawId = false  )

static

Save the state.

This function saves the state, and returns an id which can be used to retrieve it later. It will also update the $state array with the identifier.

Parameters

array	&$state	The login request state.
string	$stage	The current stage in the login process.
bool	$rawId	Return a raw ID, without a restart URL.

Returns

string Identifier which can be used to retrieve the state later.

Definition at line 194 of file State.php.

References $id, $session, $state, SimpleSAML\Logger\debug(), and SimpleSAML_Session\getSessionFromRequest().

Referenced by sspmod_saml_Auth_Source_SP\askForIdPChange(), sspmod_authtwitter_Auth_Source_Twitter\authenticate(), sspmod_authmyspace_Auth_Source_MySpace\authenticate(), sspmod_authwindowslive_Auth_Source_LiveID\authenticate(), sspmod_authlinkedin_Auth_Source_LinkedIn\authenticate(), sspmod_negotiate_Auth_Source_Negotiate\authenticate(), sspmod_authfacebook_Auth_Source_Facebook\authenticate(), sspmod_exampleauth_Auth_Source_External\authenticate(), sspmod_authYubiKey_Auth_Source_YubiKey\authenticate(), sspmod_multiauth_Auth_Source_MultiAuth\authenticate(), sspmod_core_Auth_UserPassOrgBase\authenticate(), sspmod_core_Auth_UserPassBase\authenticate(), sspmod_cas_Auth_Source_CAS\authenticate(), sspmod_cas_Auth_Source_CAS\finalStep(), SimpleSAML_IdP\handleLogoutRequest(), SimpleSAML\IdP\TraditionalLogoutHandler\logoutNextSP(), sspmod_exampleauth_Auth_Process_RedirectTest\process(), sspmod_core_Auth_Process_WarnShortSSOInterval\process(), sspmod_preprodwarning_Auth_Process_Warning\process(), sspmod_cdc_Auth_Process_CDC\process(), sspmod_authX509_Auth_Process_ExpiryWarning\process(), sspmod_expirycheck_Auth_Process_ExpiryDate\process(), sspmod_consent_Auth_Process_Consent\process(), SimpleSAML_Auth_ProcessingChain\resumeProcessing(), sspmod_saml_Auth_Source_SP\startDisco(), SimpleSAML\IdP\IFrameLogoutHandler\startLogout(), sspmod_saml_Auth_Source_SP\startSLO2(), sspmod_saml_Auth_Source_SP\startSSO1(), sspmod_saml_Auth_Source_SP\startSSO2(), sspmod_saml_Auth_Process_ExpectedAuthnContextClassRef\unauthorized(), and sspmod_authorize_Auth_Process_Authorize\unauthorized().

    {
        assert('is_array($state)');
        assert('is_string($stage)');
        assert('is_bool($rawId)');

        $return = self::getStateId($state, $rawId);
        $id = $state[self::ID];

        // Save stage
        $state[self::STAGE] = $stage;

        // Save state
        $serializedState = serialize($state);
        $session = SimpleSAML_Session::getSessionFromRequest();
        $session->setData('SimpleSAML_Auth_State', $id, $serializedState, self::getStateTimeout());

        SimpleSAML\Logger::debug('Saved state: '.var_export($return, true));

        return $return;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

throwException()

static SimpleSAML_Auth_State::throwException (   $state, SimpleSAML_Error_Exception  $exception  )

static

Throw exception to the state exception handler.

Parameters

array	$state	The state array.
SimpleSAML_Error_Exception	$exception	The exception.

Exceptions

SimpleSAML_Error_Exception

If there is no exception handler defined, it will just throw the $exception.

Definition at line 343 of file State.php.

References $id, $state, array, and SimpleSAML\Utils\HTTP\redirectTrustedURL().

Referenced by sspmod_multiauth_Auth_Source_MultiAuth\delegateAuthentication(), sspmod_negotiate_Auth_Source_Negotiate\fallBack(), SimpleSAML_IdP\handleAuthenticationRequest(), SimpleSAML_Auth_Source\initLogin(), SimpleSAML_Auth_ProcessingChain\resumeProcessing(), and sspmod_saml_Auth_Source_SP\startSSO2().

    {
        assert('is_array($state)');

        if (array_key_exists(self::EXCEPTION_HANDLER_URL, $state)) {

            // Save the exception
            $state[self::EXCEPTION_DATA] = $exception;
            $id = self::saveState($state, self::EXCEPTION_STAGE);

            // Redirect to the exception handler
            \SimpleSAML\Utils\HTTP::redirectTrustedURL(
                $state[self::EXCEPTION_HANDLER_URL],
                array(self::EXCEPTION_PARAM => $id)
            );
        } elseif (array_key_exists(self::EXCEPTION_HANDLER_FUNC, $state)) {
            // Call the exception handler
            $func = $state[self::EXCEPTION_HANDLER_FUNC];
            assert('is_callable($func)');

            call_user_func($func, $exception, $state);
            assert(false);
        } else {
            /*
             * No exception handler is defined for the current state.
             */
            throw $exception;
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

Field Documentation

$stateTimeout

SimpleSAML_Auth_State::$stateTimeout = null

staticprivate

State timeout.

Definition at line 93 of file State.php.

CLONE_ORIGINAL_ID

const SimpleSAML_Auth_State::CLONE_ORIGINAL_ID = 'SimpleSAML_Auth_State.cloneOriginalId'

The index in the cloned state array which contains the identifier of the original state.

Definition at line 45 of file State.php.

EXCEPTION_DATA

const SimpleSAML_Auth_State::EXCEPTION_DATA = 'SimpleSAML_Auth_State.exceptionData'

The index in the state array which contains the exception data.

Definition at line 75 of file State.php.

EXCEPTION_HANDLER_FUNC

const SimpleSAML_Auth_State::EXCEPTION_HANDLER_FUNC = 'SimpleSAML_Auth_State.exceptionFunc'

The index in the state array which contains the exception handler function.

Definition at line 69 of file State.php.

Referenced by sspmod_saml_IdP_SAML2\receiveAuthnRequest().

EXCEPTION_HANDLER_URL

const SimpleSAML_Auth_State::EXCEPTION_HANDLER_URL = 'SimpleSAML_Auth_State.exceptionURL'

The index in the state array which contains the exception handler URL.

Definition at line 63 of file State.php.

Referenced by SimpleSAML_Auth_Source\initLogin().

EXCEPTION_PARAM

const SimpleSAML_Auth_State::EXCEPTION_PARAM = 'SimpleSAML_Auth_State_exceptionId'

The URL parameter which contains the exception state id.

Definition at line 87 of file State.php.

EXCEPTION_STAGE

const SimpleSAML_Auth_State::EXCEPTION_STAGE = 'SimpleSAML_Auth_State.exceptionStage'

The stage of a state with an exception.

Definition at line 81 of file State.php.

ID

const SimpleSAML_Auth_State::ID = 'SimpleSAML_Auth_State.id'

The index in the state array which contains the identifier.

Definition at line 38 of file State.php.

RESTART

const SimpleSAML_Auth_State::RESTART = 'SimpleSAML_Auth_State.restartURL'

The index in the state array which contains the restart URL.

Definition at line 57 of file State.php.

Referenced by sspmod_saml_IdP_SAML1\receiveAuthnRequest(), and sspmod_saml_IdP_SAML2\receiveAuthnRequest().

STAGE

const SimpleSAML_Auth_State::STAGE = 'SimpleSAML_Auth_State.stage'

The index in the state array which contains the current stage.

Definition at line 51 of file State.php.

---

The documentation for this class was generated from the following file:

• libs/composer/vendor/simplesamlphp/simplesamlphp/lib/SimpleSAML/Auth/State.php