Authentication request for reauthenticating with elevated security. More...

Inherits MediaWiki\Auth\AuthenticationRequest.

Collaboration diagram for MediaWiki\Auth\ElevatedSecurityAuthenticationRequest:

Public Member Functions

__sleep ()

getFieldInfo ()

Fetch input field info.This will be used in the AuthManager APIs and web UIs to define API input parameters / form fields and to process the submitted data.The field info is an associative array mapping field names to info arrays. The info arrays have the following keys:

type: (string) Type of input. Types and equivalent HTML widgets are:
- string: <input type="text">
- password: <input type="password">
- select: <select>
- checkbox: <input type="checkbox">
- multiselect: More a grid of checkboxes than <select multi>
- button: <input type="submit"> (uses 'label' as button text)
- hidden: Not visible to the user, but needs to be preserved for the next request
- null: No widget, just display the 'label' message.
options: (array) Maps option values to Messages for the 'select' and 'multiselect' types.
value: (string) Value (for 'null' and 'hidden') or default value (for other types).
label: (Message) Text suitable for a label in an HTML form
help: (Message) Text suitable as a description of what the field is. Used in API documentation. To add a help text to the web UI, use the AuthChangeFormFields hook.
optional: (bool) If set and truthy, the field may be left empty
sensitive: (bool) If set and truthy, the field is considered sensitive. Code using the request should avoid exposing the value of the field.
skippable: (bool) If set and truthy, the client is free to hide this field from the user to streamline the workflow. If all fields are skippable (except possibly a single button), no user interaction is required at all.

All AuthenticationRequests are populated from the same data, so most of the time you'll want to prefix fields names with something unique to the extension/provider (although in some cases sharing the field with other requests is the right thing to do, e.g. for a 'password' field). When multiple fields have the same name, they will be merged (see AuthenticationRequests::mergeFieldInfo). Typically, AuthenticationRequest subclasses define public properties with names matching the field info keys, and those fields will be populated from the submitted data. More complex behavior can be implemented by overriding {

See also: loadFromSubmission()}.

Returns: array As above

loadFromSubmission (array $data)

Initialize form submitted form data.The default behavior is to check for each key of self::getFieldInfo() in the submitted data, and copy the value - after type-appropriate transformations - to $this->$key. Most subclasses won't need to override this; if you do override it, make sure to always return false if self::getFieldInfo() returns an empty array.

Stability: stable: to override

Parameters

array $data Submitted data as an associative array (keys will correspond to getFieldInfo())

Returns: bool Whether the request data was successfully loaded

validate ()

Validate the submitted data.This is called by AuthManager sometime after request data was loaded with loadFromSubmission(). A fatal status will stop the authentication process and result in a FAIL response. (Non-fatal error statuses are ignored for now.)This is meant for authentication errors the user is unable to fix without restarting the process (such as token expiration) or which indicate tampering with the request. Recoverable errors are better handled by methods with allow the user to redo the request without restarting the process (e.g. the AuthChangeFormFields hook).Note that this check was added in MediaWiki 1.46 so don't use it as a security guarantee if you want to support older versions as well.

Returns: StatusValue

Since: 1.46

Public Member Functions inherited from MediaWiki\Auth\AuthenticationRequest

describeCredentials ()

Describe the credentials represented by this request.

getMetadata ()

Returns metadata about this request.

getUniqueId ()

Supply a unique key for deduplication.

Static Public Member Functions
static	__set_state ( $data)
	Implementing this mainly for use from the unit tests.

static	create (Session $session, $securityLevel)
	Create a new elevated-security reauthentication request, and store its data in the current session.

Static Public Member Functions inherited from MediaWiki\Auth\AuthenticationRequest
static	getRequestByClass (array $reqs, $class, $allowSubclasses=false)
	Select a request by class name.

static	getUsernameFromRequests (array $reqs)
	Get the username from the set of requests.

static	loadRequestsFromSubmission (array $reqs, array $data)
	Update a set of requests with form submit data, discarding ones that fail.

static	mergeFieldInfo (array $reqs)
	Merge the output of multiple AuthenticationRequest::getFieldInfo() calls.

Public Attributes
string	$securityLevel
	The security level of the reauthentication process.

int	$userId
	The user who is being reauthenticated.

const int	MAX_AGE = 300
	Max allowed time between getAuthenticationRequests() and beginAuthentication().

Public Attributes inherited from MediaWiki\Auth\AuthenticationRequest
string null	$action = null
	The AuthManager::ACTION_* constant this request was created to be used for.

int	$required = self::REQUIRED
	Whether the authentication request is required (for login, continue, and link actions).

string null	$returnToUrl = null
	Return-to URL, in case of a REDIRECT AuthenticationResponse.

string null	$username = null
	Username.

const	OPTIONAL = 0
	Indicates that the request is not required for authentication to proceed.

const	PRIMARY_REQUIRED = 2
	Indicates that the request is required by a primary authentication provider.

const	REQUIRED = 1
	Indicates that the request is required for authentication to proceed.

Detailed Description

Authentication request for reauthenticating with elevated security.

Represents an elevated-security reauthentication process (ie. the user proving their identity before getting access to some security-sensitive functionality such as password change or actions restricted to highly privileged users). This request is managed by AuthManager and can be initiated by the securityLevel option of getAuthenticationRequests().

This request being present in the set of requests passed to an authentication provider means that the user is guaranteed not to change during the authentication process (but the session id might renew), and after a successful authentication the user will pass a check for AuthManager::securitySensitiveOperationStatus() with the given security level.

Since: 1.47

See also: AuthManager::getAuthenticationRequests(); AuthManager::securitySensitiveOperationStatus(); SpecialPage::checkLoginSecurityLevel()

Definition at line 31 of file ElevatedSecurityAuthenticationRequest.php.

Member Function Documentation

◆ __set_state()

static MediaWiki\Auth\ElevatedSecurityAuthenticationRequest::__set_state ( $data )

static

Implementing this mainly for use from the unit tests.

Parameters

array $data

Returns: AuthenticationRequest

Reimplemented from MediaWiki\Auth\AuthenticationRequest.

Definition at line 128 of file ElevatedSecurityAuthenticationRequest.php.

◆ __sleep()

MediaWiki\Auth\ElevatedSecurityAuthenticationRequest::__sleep ( )

Definition at line 78 of file ElevatedSecurityAuthenticationRequest.php.

◆ create()

static MediaWiki\Auth\ElevatedSecurityAuthenticationRequest::create	(	Session	$session,
			$securityLevel )

static

Create a new elevated-security reauthentication request, and store its data in the current session.

Parameters

Session	$session	The user session which will be elevated. Will be persisted.
string	$securityLevel	The security level of the reauthentication process.

Returns: ElevatedSecurityAuthenticationRequest

Access: internal: for use by AuthManager only

Definition at line 60 of file ElevatedSecurityAuthenticationRequest.php.

References MediaWiki\Auth\ElevatedSecurityAuthenticationRequest\$securityLevel, MediaWiki\Session\Session\getToken(), MediaWiki\Session\Session\getUser(), and MediaWiki\Session\Session\persist().

◆ getFieldInfo()

MediaWiki\Auth\ElevatedSecurityAuthenticationRequest::getFieldInfo ( )

Fetch input field info.This will be used in the AuthManager APIs and web UIs to define API input parameters / form fields and to process the submitted data.The field info is an associative array mapping field names to info arrays. The info arrays have the following keys:

type: (string) Type of input. Types and equivalent HTML widgets are:
- string: <input type="text">
- password: <input type="password">
- select: <select>
- checkbox: <input type="checkbox">
- multiselect: More a grid of checkboxes than <select multi>
- button: <input type="submit"> (uses 'label' as button text)
- hidden: Not visible to the user, but needs to be preserved for the next request
- null: No widget, just display the 'label' message.
options: (array) Maps option values to Messages for the 'select' and 'multiselect' types.
value: (string) Value (for 'null' and 'hidden') or default value (for other types).
label: (Message) Text suitable for a label in an HTML form
help: (Message) Text suitable as a description of what the field is. Used in API documentation. To add a help text to the web UI, use the AuthChangeFormFields hook.
optional: (bool) If set and truthy, the field may be left empty
sensitive: (bool) If set and truthy, the field is considered sensitive. Code using the request should avoid exposing the value of the field.
skippable: (bool) If set and truthy, the client is free to hide this field from the user to streamline the workflow. If all fields are skippable (except possibly a single button), no user interaction is required at all.

All AuthenticationRequests are populated from the same data, so most of the time you'll want to prefix fields names with something unique to the extension/provider (although in some cases sharing the field with other requests is the right thing to do, e.g. for a 'password' field). When multiple fields have the same name, they will be merged (see AuthenticationRequests::mergeFieldInfo). Typically, AuthenticationRequest subclasses define public properties with names matching the field info keys, and those fields will be populated from the submitted data. More complex behavior can be implemented by overriding {

See also: loadFromSubmission()}.

Returns: array As above

Reimplemented from MediaWiki\Auth\AuthenticationRequest.

Definition at line 87 of file ElevatedSecurityAuthenticationRequest.php.

References wfMessage().

◆ loadFromSubmission()

MediaWiki\Auth\ElevatedSecurityAuthenticationRequest::loadFromSubmission ( array $data )

Initialize form submitted form data.The default behavior is to check for each key of self::getFieldInfo() in the submitted data, and copy the value - after type-appropriate transformations - to $this->$key. Most subclasses won't need to override this; if you do override it, make sure to always return false if self::getFieldInfo() returns an empty array.

Stability: stable: to override

Parameters

array $data Submitted data as an associative array (keys will correspond to getFieldInfo())

Returns: bool Whether the request data was successfully loaded

Reimplemented from MediaWiki\Auth\AuthenticationRequest.

Definition at line 101 of file ElevatedSecurityAuthenticationRequest.php.

◆ validate()

MediaWiki\Auth\ElevatedSecurityAuthenticationRequest::validate ( )

Validate the submitted data.This is called by AuthManager sometime after request data was loaded with loadFromSubmission(). A fatal status will stop the authentication process and result in a FAIL response. (Non-fatal error statuses are ignored for now.)This is meant for authentication errors the user is unable to fix without restarting the process (such as token expiration) or which indicate tampering with the request. Recoverable errors are better handled by methods with allow the user to redo the request without restarting the process (e.g. the AuthChangeFormFields hook).Note that this check was added in MediaWiki 1.46 so don't use it as a security guarantee if you want to support older versions as well.