This is a value object for authentication requests. More...

Public Member Functions
	describeCredentials ()
	Describe the credentials represented by this request.

	getFieldInfo ()
	Fetch input field info.

	getMetadata ()
	Returns metadata about this request.

	getUniqueId ()
	Supply a unique key for deduplication.

	loadFromSubmission (array $data)
	Initialize form submitted form data.

	validate ()
	Validate the submitted data.

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

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

This is a value object for authentication requests.

An AuthenticationRequest represents a set of form fields that are needed on and provided from a login, account creation, password change or similar form. Form fields can be shared by multiple AuthenticationRequests (see {

See also: ::mergeFieldInfo()}).

Authentication providers that expect user input need to implement one or more subclasses of this class and return them from AuthenticationProvider::getAuthenticationRequests(). A typical subclass would override getFieldInfo() and set $required.

Stability: stable: to extend

Since: 1.27

Definition at line 29 of file AuthenticationRequest.php.

Member Function Documentation

◆ __set_state()

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

static

Implementing this mainly for use from the unit tests.

Parameters

array $data

Returns: AuthenticationRequest

Reimplemented in MediaWiki\Auth\ButtonAuthenticationRequest, MediaWiki\Auth\ConfirmLinkAuthenticationRequest, MediaWiki\Auth\ElevatedSecurityAuthenticationRequest, and MediaWiki\Auth\PasswordDomainAuthenticationRequest.

Definition at line 440 of file AuthenticationRequest.php.

◆ describeCredentials()

MediaWiki\Auth\AuthenticationRequest::describeCredentials ( )

Describe the credentials represented by this request.

This is used on requests returned by AuthenticationProvider::getAuthenticationRequests() for ACTION_LINK and ACTION_REMOVE and for requests returned in AuthenticationResponse::$linkRequest to create useful user interfaces.

Stability: stable: to override

Returns

Message[] with the following keys:

provider: A Message identifying the service that provides the credentials, e.g. the name of the third party authentication service.
account: A Message identifying the credentials themselves, e.g. the email address used with the third party authentication service.

Reimplemented in MediaWiki\Auth\PasswordAuthenticationRequest, MediaWiki\Auth\PasswordDomainAuthenticationRequest, and MediaWiki\Auth\TemporaryPasswordAuthenticationRequest.

Definition at line 277 of file AuthenticationRequest.php.

References MediaWiki\Auth\AuthenticationRequest\getUniqueId().

Referenced by MediaWiki\Specials\SpecialChangeCredentials\showSubpageList().

◆ getFieldInfo()

MediaWiki\Auth\AuthenticationRequest::getFieldInfo ( )

abstract

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

Referenced by MediaWiki\SpecialPage\AuthManagerSpecialPage\hasOwnSubmitButton(), and MediaWiki\Auth\AuthenticationRequest\loadFromSubmission().

◆ getMetadata()

MediaWiki\Auth\AuthenticationRequest::getMetadata ( )

Returns metadata about this request.

This is mainly for the benefit of API clients which need more detailed render hints than what's available through getFieldInfo(). Semantics are unspecified and left to the individual subclasses, but the contents of the array should be primitive types so that they can be transformed into JSON or similar formats.

Stability: stable: to override

Returns: array A (possibly nested) array with primitive types

Definition at line 159 of file AuthenticationRequest.php.

◆ getRequestByClass()

static MediaWiki\Auth\AuthenticationRequest::getRequestByClass	(	array	$reqs,
			$class,
			$allowSubclasses = false )

static

Select a request by class name.

@template T of AuthenticationRequest

Parameters

AuthenticationRequest[]	$reqs
	class-string<T>	$class Class name
bool	$allowSubclasses	If true, also returns any request that's a subclass of the given class.

Returns: T|null Returns null if there is not exactly one matching request.

Definition at line 312 of file AuthenticationRequest.php.

◆ getUniqueId()

MediaWiki\Auth\AuthenticationRequest::getUniqueId ( )

Supply a unique key for deduplication.

When the AuthenticationRequests instances returned by the providers are merged, the value returned here is used for keeping only one copy of duplicate requests.

Subclasses should override this if multiple distinct instances would make sense, i.e. the request class has internal state of some sort.

This value might be exposed to the user in web forms so it should not contain private information.

Stability: stable: to override

Returns: string

Reimplemented in MediaWiki\Auth\ButtonAuthenticationRequest, and MediaWiki\Auth\ConfirmLinkAuthenticationRequest.

Definition at line 101 of file AuthenticationRequest.php.

Referenced by MediaWiki\Auth\AuthenticationRequest\describeCredentials(), MediaWiki\Api\ApiRemoveAuthenticationData\execute(), and MediaWiki\Api\ApiAuthManagerHelper\loadAuthenticationRequests().

◆ getUsernameFromRequests()

static MediaWiki\Auth\AuthenticationRequest::getUsernameFromRequests ( array $reqs )

static

Get the username from the set of requests.

Only considers requests that have a "username" field.

Parameters

AuthenticationRequest[] $reqs

Returns: string|null

Exceptions

UnexpectedValueException If multiple different usernames are present.

Definition at line 333 of file AuthenticationRequest.php.

References MediaWiki\Auth\AuthenticationRequest\$username.

Referenced by MediaWiki\Auth\ThrottlePreAuthenticationProvider\testForAuthentication().

◆ loadFromSubmission()

MediaWiki\Auth\AuthenticationRequest::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 in MediaWiki\Auth\CreateFromLoginAuthenticationRequest, and MediaWiki\Auth\ElevatedSecurityAuthenticationRequest.

Definition at line 176 of file AuthenticationRequest.php.

References MediaWiki\Auth\AuthenticationRequest\getFieldInfo().

◆ loadRequestsFromSubmission()

static MediaWiki\Auth\AuthenticationRequest::loadRequestsFromSubmission	(	array	$reqs,
		array	$data )

static

Update a set of requests with form submit data, discarding ones that fail.

Parameters

AuthenticationRequest[]	$reqs
array	$data

Returns: AuthenticationRequest[]

Definition at line 291 of file AuthenticationRequest.php.

◆ mergeFieldInfo()

static MediaWiki\Auth\AuthenticationRequest::mergeFieldInfo ( array $reqs )

static

Merge the output of multiple AuthenticationRequest::getFieldInfo() calls.

Parameters

AuthenticationRequest[] $reqs

Returns: array Field info in the same format as getFieldInfo().

Exceptions

UnexpectedValueException If the requests include fields with the same name but incompatible definitions (e.g. different field types).

Definition at line 360 of file AuthenticationRequest.php.

References MediaWiki\Auth\AuthenticationRequest\$required.

◆ validate()

MediaWiki\Auth\AuthenticationRequest::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

Reimplemented in MediaWiki\Auth\ElevatedSecurityAuthenticationRequest.

Definition at line 255 of file AuthenticationRequest.php.

Referenced by MediaWiki\Auth\AuthManager\allowsAuthenticationDataChange(), and MediaWiki\Auth\AuthManager\changeAuthenticationData().

Member Data Documentation

◆ $action

string null MediaWiki\Auth\AuthenticationRequest::$action = null

The AuthManager::ACTION_* constant this request was created to be used for.

Usually set by AuthManager. The *_CONTINUE constants are not used here, the corresponding "begin" constant is used instead.

Definition at line 55 of file AuthenticationRequest.php.

Referenced by MediaWiki\Auth\CreateFromLoginAuthenticationRequest\hasPrimaryStateForAction(), and MediaWiki\Auth\CreateFromLoginAuthenticationRequest\hasStateForAction().

◆ $required

int MediaWiki\Auth\AuthenticationRequest::$required = self::REQUIRED

Whether the authentication request is required (for login, continue, and link actions).

Setting this to optional is roughly equivalent to setting the 'optional' flag for all fields in the field info.

Set this to self::OPTIONAL or self::REQUIRED. When coming from a primary provider, self::REQUIRED will be automatically modified to self::PRIMARY_REQUIRED.

Definition at line 67 of file AuthenticationRequest.php.

Referenced by MediaWiki\Auth\ButtonAuthenticationRequest\__construct(), and MediaWiki\Auth\AuthenticationRequest\mergeFieldInfo().

◆ $returnToUrl

string null MediaWiki\Auth\AuthenticationRequest::$returnToUrl = null

Return-to URL, in case of a REDIRECT AuthenticationResponse.

Set by AuthManager.

Definition at line 73 of file AuthenticationRequest.php.

◆ $username

string null MediaWiki\Auth\AuthenticationRequest::$username = null

Username.

Usually set by AuthManager. See AuthenticationProvider::getAuthenticationRequests() for details of what this means and how it behaves.

Often this doubles as a normal field (ie. getFieldInfo() has a 'username' key).

Definition at line 83 of file AuthenticationRequest.php.

Referenced by MediaWiki\Auth\AuthenticationRequest\getUsernameFromRequests().

◆ OPTIONAL

const MediaWiki\Auth\AuthenticationRequest::OPTIONAL = 0

Indicates that the request is not required for authentication to proceed.

Definition at line 32 of file AuthenticationRequest.php.

Referenced by MediaWiki\Auth\ButtonAuthenticationRequest\__construct(), and MediaWiki\Auth\ResetPasswordSecondaryAuthenticationProvider\tryReset().

◆ PRIMARY_REQUIRED

const MediaWiki\Auth\AuthenticationRequest::PRIMARY_REQUIRED = 2

Indicates that the request is required by a primary authentication provider.

Since the user can choose which primary to authenticate with, the request might or might not end up being actually required.

Definition at line 46 of file AuthenticationRequest.php.

◆ REQUIRED

const MediaWiki\Auth\AuthenticationRequest::REQUIRED = 1

Indicates that the request is required for authentication to proceed.

This will only be used for UI purposes; it is the authentication providers' responsibility to verify that all required requests are present.

Definition at line 39 of file AuthenticationRequest.php.

Referenced by MediaWiki\Auth\ButtonAuthenticationRequest\__construct(), and MediaWiki\Auth\ResetPasswordSecondaryAuthenticationProvider\tryReset().

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

includes/Auth/AuthenticationRequest.php

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ __set_state()

◆ describeCredentials()

◆ getFieldInfo()

◆ getMetadata()

◆ getRequestByClass()

◆ getUniqueId()

◆ getUsernameFromRequests()

◆ loadFromSubmission()

◆ loadRequestsFromSubmission()

◆ mergeFieldInfo()

◆ validate()

Member Data Documentation

◆ $action

◆ $required

◆ $returnToUrl

◆ $username

◆ OPTIONAL

◆ PRIMARY_REQUIRED

◆ REQUIRED