diff options
Diffstat (limited to 'www/wiki/includes/auth/SecondaryAuthenticationProvider.php')
| -rw-r--r-- | www/wiki/includes/auth/SecondaryAuthenticationProvider.php | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/www/wiki/includes/auth/SecondaryAuthenticationProvider.php b/www/wiki/includes/auth/SecondaryAuthenticationProvider.php new file mode 100644 index 00000000..c55e65d5 --- /dev/null +++ b/www/wiki/includes/auth/SecondaryAuthenticationProvider.php @@ -0,0 +1,258 @@ +<?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 ); + +} |