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.

    {
        $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;
    }

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

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.

    {
        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]);
    }

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

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.

    {
        // 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;
    }

References $key, and $state.

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

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.

    {
        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];
    }

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

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

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.

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

References $globalConfig, $stateTimeout, and SimpleSAML_Configuration\getInstance().

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.

    {
        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;
    }

References $id, $state, EXCEPTION_PARAM, and loadState().

Here is the call graph for this function:

◆ 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.

    {
        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;
    }

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

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

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.

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

References $id, $stateId, and $url.

Referenced by loadState(), and SimpleSAML_Utilities\parseStateID().

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.

    {
        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;
    }

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

Referenced by sspmod_saml_Auth_Source_SP\askForIdPChange(), sspmod_authfacebook_Auth_Source_Facebook\authenticate(), sspmod_authlinkedin_Auth_Source_LinkedIn\authenticate(), sspmod_authmyspace_Auth_Source_MySpace\authenticate(), sspmod_authtwitter_Auth_Source_Twitter\authenticate(), sspmod_authwindowslive_Auth_Source_LiveID\authenticate(), sspmod_authYubiKey_Auth_Source_YubiKey\authenticate(), sspmod_cas_Auth_Source_CAS\authenticate(), sspmod_core_Auth_UserPassBase\authenticate(), sspmod_core_Auth_UserPassOrgBase\authenticate(), sspmod_exampleauth_Auth_Source_External\authenticate(), sspmod_multiauth_Auth_Source_MultiAuth\authenticate(), sspmod_negotiate_Auth_Source_Negotiate\authenticate(), sspmod_cas_Auth_Source_CAS\finalStep(), SimpleSAML_IdP\handleLogoutRequest(), SimpleSAML\IdP\TraditionalLogoutHandler\logoutNextSP(), sspmod_authX509_Auth_Process_ExpiryWarning\process(), sspmod_cdc_Auth_Process_CDC\process(), sspmod_consent_Auth_Process_Consent\process(), sspmod_core_Auth_Process_WarnShortSSOInterval\process(), sspmod_exampleauth_Auth_Process_RedirectTest\process(), sspmod_expirycheck_Auth_Process_ExpiryDate\process(), sspmod_preprodwarning_Auth_Process_Warning\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(), throwException(), sspmod_authorize_Auth_Process_Authorize\unauthorized(), and sspmod_saml_Auth_Process_ExpectedAuthnContextClassRef\unauthorized().

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.

    {
        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;
        }
    }