diff options
Diffstat (limited to 'www/wiki/includes/auth/PreAuthenticationProvider.php')
-rw-r--r-- | www/wiki/includes/auth/PreAuthenticationProvider.php | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/www/wiki/includes/auth/PreAuthenticationProvider.php b/www/wiki/includes/auth/PreAuthenticationProvider.php new file mode 100644 index 00000000..8590cbd1 --- /dev/null +++ b/www/wiki/includes/auth/PreAuthenticationProvider.php @@ -0,0 +1,148 @@ +<?php +/** + * Pre-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 pre-authentication provider can prevent authentication early on. + * + * A PreAuthenticationProvider is used to supply arbitrary checks to be + * performed before the PrimaryAuthenticationProviders are consulted during the + * login / account creation / account linking process. Possible uses include + * checking that a per-IP throttle has not been reached or that a captcha has been solved. + * + * This interface also provides callbacks that are invoked after login / account creation + * / account linking succeeded or failed. + * + * @ingroup Auth + * @since 1.27 + * @see https://www.mediawiki.org/wiki/Manual:SessionManager_and_AuthManager + */ +interface PreAuthenticationProvider extends AuthenticationProvider { + + /** + * Determine whether an authentication may begin + * + * Called from AuthManager::beginAuthentication() + * + * @param AuthenticationRequest[] $reqs + * @return StatusValue + */ + public function testForAuthentication( 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. + * + * @note Under certain circumstances, this can be called even when testForAuthentication + * was not; see AuthenticationRequest::$loginRequest. + * @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 ); + + /** + * 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 ); + + /** + * 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-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 linked to another authentication method + * + * @param User $user User being linked. + * This may become a "UserValue" in the future, or User may be refactored + * into such. + * @return StatusValue + */ + public function testForAccountLink( $user ); + + /** + * Post-link callback + * + * This will be called at the end of an account linking attempt. + * + * @param User $user User that was attempted to be linked. + * 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 postAccountLink( $user, AuthenticationResponse $response ); + +} |