includes/auth/SecondaryAuthenticationProvider.php

   1 <?php
   2 /**
   3  * Secondary authentication provider interface
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Auth
  22  */
  23
  24 namespace MediaWiki\Auth;
  25
  26 use StatusValue;
  27 use User;
  28
  29 /**
  30  * A secondary authentication provider performs additional authentication steps
  31  * after a PrimaryAuthenticationProvider has done its thing.
  32  *
  33  * A SecondaryAuthenticationProvider is used to perform arbitrary checks on an
  34  * authentication request after the user itself has been authenticated. For
  35  * example, it might implement a password reset, request the second factor for
  36  * two-factor auth, or prevent the login if the account is blocked.
  37  *
  38  * @ingroup Auth
  39  * @since 1.27
  40  */
  41 interface SecondaryAuthenticationProvider extends AuthenticationProvider {
  42
  43         /**
  44          * Start an authentication flow
  45          *
  46          * Note that this may be called for a user even if
  47          * beginSecondaryAccountCreation() was never called. The module should take
  48          * the opportunity to do any necessary setup in that case.
  49          *
  50          * @param User $user User being authenticated. This may become a
  51          *   "UserValue" in the future, or User may be refactored into such.
  52          * @param AuthenticationRequest[] $reqs
  53          * @return AuthenticationResponse Expected responses:
  54          *  - PASS: The user is authenticated. Additional secondary providers may run.
  55          *  - FAIL: The user is not authenticated. Fail the authentication process.
  56          *  - ABSTAIN: Additional secondary providers may run.
  57          *  - UI: Additional AuthenticationRequests are needed to complete the process.
  58          *  - REDIRECT: Redirection to a third party is needed to complete the process.
  59          */
  60         public function beginSecondaryAuthentication( $user, array $reqs );
  61
  62         /**
  63          * Continue an authentication flow
  64          * @param User $user User being authenticated. This may become a
  65          *   "UserValue" in the future, or User may be refactored into such.
  66          * @param AuthenticationRequest[] $reqs
  67          * @return AuthenticationResponse Expected responses:
  68          *  - PASS: The user is authenticated. Additional secondary providers may run.
  69          *  - FAIL: The user is not authenticated. Fail the authentication process.
  70          *  - ABSTAIN: Additional secondary providers may run.
  71          *  - UI: Additional AuthenticationRequests are needed to complete the process.
  72          *  - REDIRECT: Redirection to a third party is needed to complete the process.
  73          */
  74         public function continueSecondaryAuthentication( $user, array $reqs );
  75
  76         /**
  77          * Post-login callback
  78          * @param User|null $user User that was attempted to be logged in, if known.
  79          *   This may become a "UserValue" in the future, or User may be refactored
  80          *   into such.
  81          * @param AuthenticationResponse $response Authentication response that will be returned
  82          */
  83         public function postAuthentication( $user, AuthenticationResponse $response );
  84
  85         /**
  86          * Revoke the user's credentials
  87          *
  88          * This may cause the user to no longer exist for the provider, or the user
  89          * may continue to exist in a "disabled" state.
  90          *
  91          * The intention is that the named account will never again be usable for
  92          * normal login (i.e. there is no way to undo the revocation of access).
  93          *
  94          * @param string $username
  95          */
  96         public function providerRevokeAccessForUser( $username );
  97
  98         /**
  99          * Determine whether a property can change
 100          * @see AuthManager::allowsPropertyChange()
 101          * @param string $property
 102          * @return bool
 103          */
 104         public function providerAllowsPropertyChange( $property );
 105
 106         /**
 107          * Validate a change of authentication data (e.g. passwords)
 108          *
 109          * Return StatusValue::newGood( 'ignored' ) if you don't support this
 110          * AuthenticationRequest type.
 111          *
 112          * @param AuthenticationRequest $req
 113          * @param bool $checkData If false, $req hasn't been loaded from the
 114          *  submission so checks on user-submitted fields should be skipped.
 115          *  $req->username is considered user-submitted for this purpose, even
 116          *  if it cannot be changed via $req->loadFromSubmission.
 117          * @return StatusValue
 118          */
 119         public function providerAllowsAuthenticationDataChange(
 120                 AuthenticationRequest $req, $checkData = true
 121         );
 122
 123         /**
 124          * Change or remove authentication data (e.g. passwords)
 125          *
 126          * If $req was returned for AuthManager::ACTION_CHANGE, the corresponding
 127          * credentials should result in a successful login in the future.
 128          *
 129          * If $req was returned for AuthManager::ACTION_REMOVE, the corresponding
 130          * credentials should no longer result in a successful login.
 131          *
 132          * @param AuthenticationRequest $req
 133          */
 134         public function providerChangeAuthenticationData( AuthenticationRequest $req );
 135
 136         /**
 137          * Determine whether an account creation may begin
 138          *
 139          * Called from AuthManager::beginAccountCreation()
 140          *
 141          * @note No need to test if the account exists, AuthManager checks that
 142          * @param User $user User being created (not added to the database yet).
 143          *   This may become a "UserValue" in the future, or User may be refactored
 144          *   into such.
 145          * @param User $creator User doing the creation. This may become a
 146          *   "UserValue" in the future, or User may be refactored into such.
 147          * @param AuthenticationRequest[] $reqs
 148          * @return StatusValue
 149          */
 150         public function testForAccountCreation( $user, $creator, array $reqs );
 151
 152         /**
 153          * Start an account creation flow
 154          * @param User $user User being created (has been added to the database).
 155          *   This may become a "UserValue" in the future, or User may be refactored
 156          *   into such.
 157          * @param User $creator User doing the creation. This may become a
 158          *   "UserValue" in the future, or User may be refactored into such.
 159          * @param AuthenticationRequest[] $reqs
 160          * @return AuthenticationResponse Expected responses:
 161          *  - PASS: The user creation is ok. Additional secondary providers may run.
 162          *  - ABSTAIN: Additional secondary providers may run.
 163          *  - UI: Additional AuthenticationRequests are needed to complete the process.
 164          *  - REDIRECT: Redirection to a third party is needed to complete the process.
 165          */
 166         public function beginSecondaryAccountCreation( $user, $creator, array $reqs );
 167
 168         /**
 169          * Continue an authentication flow
 170          * @param User $user User being created (has been added to the database).
 171          *   This may become a "UserValue" in the future, or User may be refactored
 172          *   into such.
 173          * @param User $creator User doing the creation. This may become a
 174          *   "UserValue" in the future, or User may be refactored into such.
 175          * @param AuthenticationRequest[] $reqs
 176          * @return AuthenticationResponse Expected responses:
 177          *  - PASS: The user creation is ok. Additional secondary providers may run.
 178          *  - ABSTAIN: Additional secondary providers may run.
 179          *  - UI: Additional AuthenticationRequests are needed to complete the process.
 180          *  - REDIRECT: Redirection to a third party is needed to complete the process.
 181          */
 182         public function continueSecondaryAccountCreation( $user, $creator, array $reqs );
 183
 184         /**
 185          * Post-creation callback
 186          * @param User $user User that was attempted to be created.
 187          *   This may become a "UserValue" in the future, or User may be refactored
 188          *   into such.
 189          * @param User $creator User doing the creation. This may become a
 190          *   "UserValue" in the future, or User may be refactored into such.
 191          * @param AuthenticationResponse $response Authentication response that will be returned
 192          */
 193         public function postAccountCreation( $user, $creator, AuthenticationResponse $response );
 194
 195         /**
 196          * Determine whether an account may be created
 197          *
 198          * @param User $user User being created (not added to the database yet).
 199          *   This may become a "UserValue" in the future, or User may be refactored
 200          *   into such.
 201          * @param bool|string $autocreate False if this is not an auto-creation, or
 202          *  the source of the auto-creation passed to AuthManager::autoCreateUser().
 203          * @param array $options
 204          *  - flags: (int) Bitfield of User:READ_* constants, default User::READ_NORMAL
 205          *  - creating: (bool) If false (or missing), this call is only testing if
 206          *    a user could be created. If set, this (non-autocreation) is for
 207          *    actually creating an account and will be followed by a call to
 208          *    testForAccountCreation(). In this case, the provider might return
 209          *    StatusValue::newGood() here and let the later call to
 210          *    testForAccountCreation() do a more thorough test.
 211          * @return StatusValue
 212          */
 213         public function testUserForCreation( $user, $autocreate, array $options = [] );
 214
 215         /**
 216          * Post-auto-creation callback
 217          * @param User $user User being created (has been added to the database now).
 218          *   This may become a "UserValue" in the future, or User may be refactored
 219          *   into such.
 220          * @param string $source The source of the auto-creation passed to
 221          *  AuthManager::autoCreateUser().
 222          */
 223         public function autoCreatedAccount( $user, $source );
 224
 225 }