BlueSpice MediaWiki master
 All Classes Namespaces Files Functions Variables Groups Pages
MediaWiki\Auth\AuthManager Class Reference
Inheritance diagram for MediaWiki\Auth\AuthManager:
Collaboration diagram for MediaWiki\Auth\AuthManager:

Public Member Functions

 __construct (WebRequest $request, Config $config)
 
 setLogger (LoggerInterface $logger)
 
 getRequest ()
 
 forcePrimaryAuthenticationProviders (array $providers, $why)
 
Authentication
 canAuthenticateNow ()
 
 beginAuthentication (array $reqs, $returnToUrl)
 
 securitySensitiveOperationStatus ($operation)
 
 userCanAuthenticate ($username)
 
 normalizeUsername ($username)
 
Authentication data changing
 revokeAccessForUser ($username)
 
 allowsAuthenticationDataChange (AuthenticationRequest $req, $checkData=true)
 
 changeAuthenticationData (AuthenticationRequest $req)
 
Account creation
 canCreateAccounts ()
 
 canCreateAccount ($username, $options=[])
 
 checkAccountCreatePermissions (User $creator)
 
 beginAccountCreation (User $creator, array $reqs, $returnToUrl)
 
 autoCreateUser (User $user, $source, $login=true)
 
Account linking
 canLinkAccounts ()
 
 beginAccountLink (User $user, array $reqs, $returnToUrl)
 
 continueAccountLink (array $reqs)
 

Static Public Member Functions

static singleton ()
 
static callLegacyAuthPlugin ($method, array $params, $return=null)
 

Public Attributes

const ACTION_LOGIN = 'login'
 
const ACTION_LOGIN_CONTINUE = 'login-continue'
 
const ACTION_CREATE = 'create'
 
const ACTION_CREATE_CONTINUE = 'create-continue'
 
const ACTION_LINK = 'link'
 
const ACTION_LINK_CONTINUE = 'link-continue'
 
const ACTION_CHANGE = 'change'
 
const ACTION_REMOVE = 'remove'
 
const ACTION_UNLINK = 'unlink'
 
const SEC_OK = 'ok'
 
const SEC_REAUTH = 'reauth'
 
const SEC_FAIL = 'fail'
 
const AUTOCREATE_SOURCE_SESSION = \MediaWiki\Session\SessionManager::class
 

Information methods

 getAuthenticationRequests ($action, User $user=null)
 
 userExists ($username, $flags=User::READ_NORMAL)
 
 allowsPropertyChange ($property)
 
 getAuthenticationProvider ($id)
 

Internal methods

static resetCache ()
 
 setAuthenticationSessionData ($key, $data)
 
 getAuthenticationSessionData ($key, $default=null)
 
 removeAuthenticationSessionData ($key)
 
 providerArrayFromSpecs ($class, array $specs)
 
 getPreAuthenticationProviders ()
 
 getPrimaryAuthenticationProviders ()
 
 getSecondaryAuthenticationProviders ()
 

Detailed Description

This serves as the entry point to the authentication system.

In the future, it may also serve as the entry point to the authorization system.

If you are looking at this because you are working on an extension that creates its own login or signup page, then 1) you really shouldn't do that, 2) if you feel you absolutely have to, subclass AuthManagerSpecialPage or build it on the client side using the clientlogin or the createaccount API. Trying to call this class directly will very likely end up in security vulnerabilities or broken UX in edge cases.

If you are working on an extension that needs to integrate with the authentication system (e.g. by providing a new login method, or doing extra permission checks), you'll probably need to write an AuthenticationProvider.

If you want to create a "reserved" user programmatically, User::newSystemUser() might be what you are looking for. If you want to change user data, use User::changeAuthenticationData(). Code that is related to some SessionProvider or PrimaryAuthenticationProvider can create a (non-reserved) user by calling AuthManager::autoCreateUser(); it is then the provider's responsibility to ensure that the user can authenticate somehow (see especially PrimaryAuthenticationProvider::autoCreatedAccount()). If you are writing code that is not associated with such a provider and needs to create accounts programmatically for real users, you should rethink your architecture. There is no good way to do that as such code has no knowledge of what authentication methods are enabled on the wiki and cannot provide any means for users to access the accounts it would create.

The two main control flows when using this class are as follows:

  • Login, user creation or account linking code will call getAuthenticationRequests(), populate the requests with data (by using them to build a HTMLForm and have the user fill it, or by exposing a form specification via the API, so that the client can build it), and pass them to the appropriate begin* method. That will return either a success/failure response, or more requests to fill (either by building a form or by redirecting the user to some external provider which will send the data back), in which case they need to be submitted to the appropriate continue* method and that step has to be repeated until the response is a success or failure response. AuthManager will use the session to maintain internal state during the process.
  • Code doing an authentication data change will call getAuthenticationRequests(), select a single request, populate it, and pass it to allowsAuthenticationDataChange() and then changeAuthenticationData(). If the data change is user-initiated, the whole process needs to be preceded by a call to securitySensitiveOperationStatus() and aborted if that returns a non-OK status.
Since
1.27
See Also
https://www.mediawiki.org/wiki/Manual:SessionManager_and_AuthManager

Constructor & Destructor Documentation

MediaWiki\Auth\AuthManager::__construct ( WebRequest  $request,
Config  $config 
)
Parameters
WebRequest$request
Config$config

Member Function Documentation

MediaWiki\Auth\AuthManager::allowsAuthenticationDataChange ( AuthenticationRequest  $req,
  $checkData = true 
)

Validate a change of authentication data (e.g. passwords)

Parameters
AuthenticationRequest$req
bool$checkDataIf false, $req hasn't been loaded from the submission so checks on user-submitted fields should be skipped. $req->username is considered user-submitted for this purpose, even if it cannot be changed via $req->loadFromSubmission.
Returns
Status
MediaWiki\Auth\AuthManager::allowsPropertyChange (   $property)

Determine whether a user property should be allowed to be changed.

Supported properties are:

  • emailaddress
  • realname
  • nickname
Parameters
string$property
Returns
bool
MediaWiki\Auth\AuthManager::autoCreateUser ( User  $user,
  $source,
  $login = true 
)

Auto-create an account, and log into that account

PrimaryAuthenticationProviders can invoke this method by returning a PASS from beginPrimaryAuthentication/continuePrimaryAuthentication with the username of a non-existing user. SessionProviders can invoke it by returning a SessionInfo with the username of a non-existing user from provideSessionInfo(). Calling this method explicitly (e.g. from a maintenance script) is also fine.

Parameters
User$userUser to auto-create
string$sourceWhat caused the auto-creation? This must be the ID of a PrimaryAuthenticationProvider or the constant self::AUTOCREATE_SOURCE_SESSION.
bool$loginWhether to also log the user in
Returns
Status Good if user was created, Ok if user already existed, otherwise Fatal
MediaWiki\Auth\AuthManager::beginAccountCreation ( User  $creator,
array  $reqs,
  $returnToUrl 
)

Start an account creation flow

In addition to the AuthenticationRequests returned by $this->getAuthenticationRequests(), a client might include a CreateFromLoginAuthenticationRequest from a previous login attempt. If $createFromLoginAuthenticationRequest->hasPrimaryStateForAction( AuthManager::ACTION_CREATE ) returns true, any AuthenticationRequest::PRIMARY_REQUIRED requests should be omitted. If the CreateFromLoginAuthenticationRequest has a username set, that username must be used for all other requests.

Parameters
User$creatorUser doing the account creation
AuthenticationRequest[]$reqs
string$returnToUrlUrl that REDIRECT responses should eventually return to.
Returns
AuthenticationResponse
MediaWiki\Auth\AuthManager::beginAccountLink ( User  $user,
array  $reqs,
  $returnToUrl 
)

Start an account linking flow

Parameters
User$userUser being linked
AuthenticationRequest[]$reqs
string$returnToUrlUrl that REDIRECT responses should eventually return to.
Returns
AuthenticationResponse
MediaWiki\Auth\AuthManager::beginAuthentication ( array  $reqs,
  $returnToUrl 
)

Start an authentication flow

In addition to the AuthenticationRequests returned by $this->getAuthenticationRequests(), a client might include a CreateFromLoginAuthenticationRequest from a previous login attempt to preserve state.

Instead of the AuthenticationRequests returned by $this->getAuthenticationRequests(), a client might pass a CreatedAccountAuthenticationRequest from an account creation that just succeeded to log in to the just-created account.

Parameters
AuthenticationRequest[]$reqs
string$returnToUrlUrl that REDIRECT responses should eventually return to.
Returns
AuthenticationResponse See self::continueAuthentication()
static MediaWiki\Auth\AuthManager::callLegacyAuthPlugin (   $method,
array  $params,
  $return = null 
)
static

Call a legacy AuthPlugin method, if necessary

Deprecated:
For backwards compatibility only, should be avoided in new code
Parameters
string$methodAuthPlugin method to call
array$paramsParameters to pass
mixed$returnReturn value if AuthPlugin wasn't called
Returns
mixed Return value from the AuthPlugin method, or $return
MediaWiki\Auth\AuthManager::canAuthenticateNow ( )

Indicate whether user authentication is possible

It may not be if the session is provided by something like OAuth for which each individual request includes authentication data.

Returns
bool
MediaWiki\Auth\AuthManager::canCreateAccount (   $username,
  $options = [] 
)

Determine whether a particular account can be created

Parameters
string$usernameMediaWiki username
array$options
  • flags: (int) Bitfield of User:READ_* constants, default User::READ_NORMAL
  • creating: (bool) For internal use only. Never specify this.
Returns
Status
MediaWiki\Auth\AuthManager::canCreateAccounts ( )

Determine whether accounts can be created

Returns
bool
MediaWiki\Auth\AuthManager::canLinkAccounts ( )

Determine whether accounts can be linked

Returns
bool
MediaWiki\Auth\AuthManager::changeAuthenticationData ( AuthenticationRequest  $req)

Change authentication data (e.g. passwords)

If $req was returned for AuthManager::ACTION_CHANGE, using $req should result in a successful login in the future.

If $req was returned for AuthManager::ACTION_REMOVE, using $req should no longer result in a successful login.

This method should only be called if allowsAuthenticationDataChange( $req, true ) returned success.

Parameters
AuthenticationRequest$req
MediaWiki\Auth\AuthManager::checkAccountCreatePermissions ( User  $creator)

Basic permissions checks on whether a user can create accounts

Parameters
User$creatorUser doing the account creation
Returns
Status
MediaWiki\Auth\AuthManager::continueAccountLink ( array  $reqs)

Continue an account linking flow

Parameters
AuthenticationRequest[]$reqs
Returns
AuthenticationResponse
MediaWiki\Auth\AuthManager::forcePrimaryAuthenticationProviders ( array  $providers,
  $why 
)

Force certain PrimaryAuthenticationProviders

Deprecated:
For backwards compatibility only
Parameters
PrimaryAuthenticationProvider[]$providers
string$why
MediaWiki\Auth\AuthManager::getAuthenticationProvider (   $id)

Get a provider by ID

Note
This is public so extensions can check whether their own provider is installed and so they can read its configuration if necessary. Other uses are not recommended.
Parameters
string$id
Returns
AuthenticationProvider|null
MediaWiki\Auth\AuthManager::getAuthenticationRequests (   $action,
User  $user = null 
)

Return the applicable list of AuthenticationRequests

Possible values for $action:

  • ACTION_LOGIN: Valid for passing to beginAuthentication
  • ACTION_LOGIN_CONTINUE: Valid for passing to continueAuthentication in the current state
  • ACTION_CREATE: Valid for passing to beginAccountCreation
  • ACTION_CREATE_CONTINUE: Valid for passing to continueAccountCreation in the current state
  • ACTION_LINK: Valid for passing to beginAccountLink
  • ACTION_LINK_CONTINUE: Valid for passing to continueAccountLink in the current state
  • ACTION_CHANGE: Valid for passing to changeAuthenticationData to change credentials
  • ACTION_REMOVE: Valid for passing to changeAuthenticationData to remove credentials.
  • ACTION_UNLINK: Same as ACTION_REMOVE, but limited to linked accounts.
Parameters
string$actionOne of the AuthManager::ACTION_* constants
User | null$userUser being acted on, instead of the current user.
Returns
AuthenticationRequest[]
MediaWiki\Auth\AuthManager::getAuthenticationSessionData (   $key,
  $default = null 
)

Fetch authentication data from the current session For use by AuthenticationProviders

Parameters
string$key
mixed$default
Returns
mixed
MediaWiki\Auth\AuthManager::getPreAuthenticationProviders ( )
protected

Get the list of PreAuthenticationProviders

Returns
PreAuthenticationProvider[]
MediaWiki\Auth\AuthManager::getPrimaryAuthenticationProviders ( )
protected

Get the list of PrimaryAuthenticationProviders

Returns
PrimaryAuthenticationProvider[]
MediaWiki\Auth\AuthManager::getRequest ( )
Returns
WebRequest
MediaWiki\Auth\AuthManager::getSecondaryAuthenticationProviders ( )
protected

Get the list of SecondaryAuthenticationProviders

Returns
SecondaryAuthenticationProvider[]
MediaWiki\Auth\AuthManager::normalizeUsername (   $username)

Provide normalized versions of the username for security checks

Since different providers can normalize the input in different ways, this returns an array of all the different ways the name might be normalized for authentication.

The returned strings should not be revealed to the user, as that might leak private information (e.g. an email address might be normalized to a username).

Parameters
string$username
Returns
string[]
MediaWiki\Auth\AuthManager::providerArrayFromSpecs (   $class,
array  $specs 
)
protected

Create an array of AuthenticationProviders from an array of ObjectFactory specs

Parameters
string$class
array[]$specs
Returns
AuthenticationProvider[]
MediaWiki\Auth\AuthManager::removeAuthenticationSessionData (   $key)

Remove authentication data For use by AuthenticationProviders

Parameters
string | null$keyIf null, all data is removed
static MediaWiki\Auth\AuthManager::resetCache ( )
static

Reset the internal caching for unit testing Unit tests only

MediaWiki\Auth\AuthManager::revokeAccessForUser (   $username)

Revoke any authentication credentials for a user

After this, the user should no longer be able to log in.

Parameters
string$username
MediaWiki\Auth\AuthManager::securitySensitiveOperationStatus (   $operation)

Whether security-sensitive operations should proceed.

A "security-sensitive operation" is something like a password or email change, that would normally have a "reenter your password to confirm" box if we only supported password-based authentication.

Parameters
string$operationOperation being checked. This should be a message-key-like string such as 'change-password' or 'change-email'.
Returns
string One of the SEC_* constants.
MediaWiki\Auth\AuthManager::setAuthenticationSessionData (   $key,
  $data 
)

Store authentication in the current session For use by AuthenticationProviders

Parameters
string$key
mixed$dataMust be serializable
MediaWiki\Auth\AuthManager::setLogger ( LoggerInterface  $logger)
Parameters
LoggerInterface$logger

Implements Psr\Log\LoggerAwareInterface.

static MediaWiki\Auth\AuthManager::singleton ( )
static

Get the global AuthManager

Returns
AuthManager
MediaWiki\Auth\AuthManager::userCanAuthenticate (   $username)

Determine whether a username can authenticate

This is mainly for internal purposes and only takes authentication data into account, not things like blocks that can change without the authentication system being aware.

Parameters
string$usernameMediaWiki username
Returns
bool
MediaWiki\Auth\AuthManager::userExists (   $username,
  $flags = User::READ_NORMAL 
)

Determine whether a username exists

Parameters
string$username
int$flagsBitfield of User:READ_* constants
Returns
bool

Member Data Documentation

const MediaWiki\Auth\AuthManager::ACTION_CHANGE = 'change'

Change a user's credentials

const MediaWiki\Auth\AuthManager::ACTION_CREATE = 'create'

Create a new user

const MediaWiki\Auth\AuthManager::ACTION_CREATE_CONTINUE = 'create-continue'

Continue a user creation process that was interrupted by the need for user input or communication with an external provider

const MediaWiki\Auth\AuthManager::ACTION_LINK = 'link'

Link an existing user to a third-party account

const MediaWiki\Auth\AuthManager::ACTION_LINK_CONTINUE = 'link-continue'

Continue a user linking process that was interrupted by the need for user input or communication with an external provider

const MediaWiki\Auth\AuthManager::ACTION_LOGIN = 'login'

Log in with an existing (not necessarily local) user

const MediaWiki\Auth\AuthManager::ACTION_LOGIN_CONTINUE = 'login-continue'

Continue a login process that was interrupted by the need for user input or communication with an external provider

const MediaWiki\Auth\AuthManager::ACTION_REMOVE = 'remove'

Remove a user's credentials

const MediaWiki\Auth\AuthManager::ACTION_UNLINK = 'unlink'

Like ACTION_REMOVE but for linking providers only

const MediaWiki\Auth\AuthManager::AUTOCREATE_SOURCE_SESSION = \MediaWiki\Session\SessionManager::class

Auto-creation is due to SessionManager

const MediaWiki\Auth\AuthManager::SEC_FAIL = 'fail'

Security-sensitive should not be performed.

const MediaWiki\Auth\AuthManager::SEC_OK = 'ok'

Security-sensitive operations are ok.

const MediaWiki\Auth\AuthManager::SEC_REAUTH = 'reauth'

Security-sensitive operations should re-authenticate.


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