258 lines
11 KiB
PHP
258 lines
11 KiB
PHP
<?php
|
|
/**
|
|
* Secondary authentication provider interface
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
* @ingroup Auth
|
|
*/
|
|
|
|
namespace MediaWiki\Auth;
|
|
|
|
use StatusValue;
|
|
use User;
|
|
|
|
/**
|
|
* A secondary provider mostly acts when the submitted authentication data has
|
|
* already been associated to a MediaWiki user account.
|
|
*
|
|
* For login, a secondary provider performs additional authentication steps
|
|
* after a PrimaryAuthenticationProvider has identified which MediaWiki user is
|
|
* trying to log in. For example, it might implement a password reset, request
|
|
* the second factor for two-factor auth, or prevent the login if the account is blocked.
|
|
*
|
|
* For account creation, a secondary provider performs optional extra steps after
|
|
* a PrimaryAuthenticationProvider has created the user; for example, it can collect
|
|
* further user information such as a biography.
|
|
*
|
|
* (For account linking, secondary providers are not involved.)
|
|
*
|
|
* This interface also provides methods for changing authentication data such
|
|
* as a second-factor token, and callbacks that are invoked after login / account creation
|
|
* succeeded or failed.
|
|
*
|
|
* @ingroup Auth
|
|
* @since 1.27
|
|
* @see https://www.mediawiki.org/wiki/Manual:SessionManager_and_AuthManager
|
|
*/
|
|
interface SecondaryAuthenticationProvider extends AuthenticationProvider {
|
|
|
|
/**
|
|
* Start an authentication flow
|
|
*
|
|
* Note that this may be called for a user even if
|
|
* beginSecondaryAccountCreation() was never called. The module should take
|
|
* the opportunity to do any necessary setup in that case.
|
|
*
|
|
* @param User $user User being authenticated. This may become a
|
|
* "UserValue" in the future, or User may be refactored into such.
|
|
* @param AuthenticationRequest[] $reqs
|
|
* @return AuthenticationResponse Expected responses:
|
|
* - PASS: The user is authenticated. Additional secondary providers may run.
|
|
* - FAIL: The user is not authenticated. Fail the authentication process.
|
|
* - ABSTAIN: Additional secondary providers may run.
|
|
* - UI: Additional AuthenticationRequests are needed to complete the process.
|
|
* - REDIRECT: Redirection to a third party is needed to complete the process.
|
|
*/
|
|
public function beginSecondaryAuthentication( $user, array $reqs );
|
|
|
|
/**
|
|
* Continue an authentication flow
|
|
* @param User $user User being authenticated. This may become a
|
|
* "UserValue" in the future, or User may be refactored into such.
|
|
* @param AuthenticationRequest[] $reqs
|
|
* @return AuthenticationResponse Expected responses:
|
|
* - PASS: The user is authenticated. Additional secondary providers may run.
|
|
* - FAIL: The user is not authenticated. Fail the authentication process.
|
|
* - ABSTAIN: Additional secondary providers may run.
|
|
* - UI: Additional AuthenticationRequests are needed to complete the process.
|
|
* - REDIRECT: Redirection to a third party is needed to complete the process.
|
|
*/
|
|
public function continueSecondaryAuthentication( $user, array $reqs );
|
|
|
|
/**
|
|
* Post-login callback
|
|
*
|
|
* This will be called at the end of a login attempt. It will not be called for unfinished
|
|
* login attempts that fail by the session timing out.
|
|
*
|
|
* @param User|null $user User that was attempted to be logged in, if known.
|
|
* This may become a "UserValue" in the future, or User may be refactored
|
|
* into such.
|
|
* @param AuthenticationResponse $response Authentication response that will be returned
|
|
* (PASS or FAIL)
|
|
*/
|
|
public function postAuthentication( $user, AuthenticationResponse $response );
|
|
|
|
/**
|
|
* Revoke the user's credentials
|
|
*
|
|
* This may cause the user to no longer exist for the provider, or the user
|
|
* may continue to exist in a "disabled" state.
|
|
*
|
|
* The intention is that the named account will never again be usable for
|
|
* normal login (i.e. there is no way to undo the revocation of access).
|
|
*
|
|
* @param string $username
|
|
*/
|
|
public function providerRevokeAccessForUser( $username );
|
|
|
|
/**
|
|
* Determine whether a property can change
|
|
* @see AuthManager::allowsPropertyChange()
|
|
* @param string $property
|
|
* @return bool
|
|
*/
|
|
public function providerAllowsPropertyChange( $property );
|
|
|
|
/**
|
|
* Validate a change of authentication data (e.g. passwords)
|
|
*
|
|
* Return StatusValue::newGood( 'ignored' ) if you don't support this
|
|
* AuthenticationRequest type.
|
|
*
|
|
* @param AuthenticationRequest $req
|
|
* @param bool $checkData If 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.
|
|
* @return StatusValue
|
|
*/
|
|
public function providerAllowsAuthenticationDataChange(
|
|
AuthenticationRequest $req, $checkData = true
|
|
);
|
|
|
|
/**
|
|
* Change or remove authentication data (e.g. passwords)
|
|
*
|
|
* If $req was returned for AuthManager::ACTION_CHANGE, the corresponding
|
|
* credentials should result in a successful login in the future.
|
|
*
|
|
* If $req was returned for AuthManager::ACTION_REMOVE, the corresponding
|
|
* credentials should no longer result in a successful login.
|
|
*
|
|
* It can be assumed that providerAllowsAuthenticationDataChange with $checkData === true
|
|
* was called before this, and passed. This method should never fail (other than throwing an
|
|
* exception).
|
|
*
|
|
* @param AuthenticationRequest $req
|
|
*/
|
|
public function providerChangeAuthenticationData( AuthenticationRequest $req );
|
|
|
|
/**
|
|
* Determine whether an account creation may begin
|
|
*
|
|
* Called from AuthManager::beginAccountCreation()
|
|
*
|
|
* @note No need to test if the account exists, AuthManager checks that
|
|
* @param User $user User being created (not added to the database yet).
|
|
* This may become a "UserValue" in the future, or User may be refactored
|
|
* into such.
|
|
* @param User $creator User doing the creation. This may become a
|
|
* "UserValue" in the future, or User may be refactored into such.
|
|
* @param AuthenticationRequest[] $reqs
|
|
* @return StatusValue
|
|
*/
|
|
public function testForAccountCreation( $user, $creator, array $reqs );
|
|
|
|
/**
|
|
* Start an account creation flow
|
|
*
|
|
* @note There is no guarantee this will be called in a successful account
|
|
* creation process as the user can just abandon the process at any time
|
|
* after the primary provider has issued a PASS and still have a valid
|
|
* account. Be prepared to handle any database inconsistencies that result
|
|
* from this or continueSecondaryAccountCreation() not being called.
|
|
* @param User $user User being created (has been added to the database).
|
|
* This may become a "UserValue" in the future, or User may be refactored
|
|
* into such.
|
|
* @param User $creator User doing the creation. This may become a
|
|
* "UserValue" in the future, or User may be refactored into such.
|
|
* @param AuthenticationRequest[] $reqs
|
|
* @return AuthenticationResponse Expected responses:
|
|
* - PASS: The user creation is ok. Additional secondary providers may run.
|
|
* - ABSTAIN: Additional secondary providers may run.
|
|
* - UI: Additional AuthenticationRequests are needed to complete the process.
|
|
* - REDIRECT: Redirection to a third party is needed to complete the process.
|
|
*/
|
|
public function beginSecondaryAccountCreation( $user, $creator, array $reqs );
|
|
|
|
/**
|
|
* Continue an authentication flow
|
|
*
|
|
* @param User $user User being created (has been added to the database).
|
|
* This may become a "UserValue" in the future, or User may be refactored
|
|
* into such.
|
|
* @param User $creator User doing the creation. This may become a
|
|
* "UserValue" in the future, or User may be refactored into such.
|
|
* @param AuthenticationRequest[] $reqs
|
|
* @return AuthenticationResponse Expected responses:
|
|
* - PASS: The user creation is ok. Additional secondary providers may run.
|
|
* - ABSTAIN: Additional secondary providers may run.
|
|
* - UI: Additional AuthenticationRequests are needed to complete the process.
|
|
* - REDIRECT: Redirection to a third party is needed to complete the process.
|
|
*/
|
|
public function continueSecondaryAccountCreation( $user, $creator, array $reqs );
|
|
|
|
/**
|
|
* Post-creation callback
|
|
*
|
|
* This will be called at the end of an account creation attempt. It will not be called if
|
|
* the account creation process results in a session timeout (possibly after a successful
|
|
* user creation, while a secondary provider is waiting for a response).
|
|
*
|
|
* @param User $user User that was attempted to be created.
|
|
* This may become a "UserValue" in the future, or User may be refactored
|
|
* into such.
|
|
* @param User $creator User doing the creation. This may become a
|
|
* "UserValue" in the future, or User may be refactored into such.
|
|
* @param AuthenticationResponse $response Authentication response that will be returned
|
|
* (PASS or FAIL)
|
|
*/
|
|
public function postAccountCreation( $user, $creator, AuthenticationResponse $response );
|
|
|
|
/**
|
|
* Determine whether an account may be created
|
|
*
|
|
* @param User $user User being created (not added to the database yet).
|
|
* This may become a "UserValue" in the future, or User may be refactored
|
|
* into such.
|
|
* @param bool|string $autocreate False if this is not an auto-creation, or
|
|
* the source of the auto-creation passed to AuthManager::autoCreateUser().
|
|
* @param array $options
|
|
* - flags: (int) Bitfield of User:READ_* constants, default User::READ_NORMAL
|
|
* - creating: (bool) If false (or missing), this call is only testing if
|
|
* a user could be created. If set, this (non-autocreation) is for
|
|
* actually creating an account and will be followed by a call to
|
|
* testForAccountCreation(). In this case, the provider might return
|
|
* StatusValue::newGood() here and let the later call to
|
|
* testForAccountCreation() do a more thorough test.
|
|
* @return StatusValue
|
|
*/
|
|
public function testUserForCreation( $user, $autocreate, array $options = [] );
|
|
|
|
/**
|
|
* Post-auto-creation callback
|
|
* @param User $user User being created (has been added to the database now).
|
|
* This may become a "UserValue" in the future, or User may be refactored
|
|
* into such.
|
|
* @param string $source The source of the auto-creation passed to
|
|
* AuthManager::autoCreateUser().
|
|
*/
|
|
public function autoCreatedAccount( $user, $source );
|
|
|
|
}
|