includes/auth/PrimaryAuthenticationProvider.php

   1 <?php
   2 /**
   3  * Primary 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 primary authentication provider determines which user is trying to log in.
  31  *
  32  * A PrimaryAuthenticationProvider is used as part of presenting a login form
  33  * to authenticate a user. In particular, the PrimaryAuthenticationProvider
  34  * takes form data and determines the authenticated user (if any) corresponds
  35  * to that form data. It might do this on the basis of a username and password
  36  * in that data, or by interacting with an external authentication service
  37  * (e.g. using OpenID), or by some other mechanism.
  38  *
  39  * A PrimaryAuthenticationProvider would not be appropriate for something like
  40  * HTTP authentication, OAuth, or SSL client certificates where each HTTP
  41  * request contains all the information needed to identify the user. In that
  42  * case you'll want to be looking at a \\MediaWiki\\Session\\SessionProvider
  43  * instead.
  44  *
  45  * This interface also provides methods for changing authentication data such
  46  * as passwords and for creating new users who can later be authenticated with
  47  * this provider.
  48  *
  49  * @ingroup Auth
  50  * @since 1.27
  51  */
  52 interface PrimaryAuthenticationProvider extends AuthenticationProvider {
  53         /** Provider can create accounts */
  54         const TYPE_CREATE = 'create';
  55         /** Provider can link to existing accounts elsewhere */
  56         const TYPE_LINK = 'link';
  57         /** Provider cannot create or link to accounts */
  58         const TYPE_NONE = 'none';
  59
  60         /**
  61          * Start an authentication flow
  62          *
  63          * @param AuthenticationRequest[] $reqs
  64          * @return AuthenticationResponse Expected responses:
  65          *  - PASS: The user is authenticated. Secondary providers will now run.
  66          *  - FAIL: The user is not authenticated. Fail the authentication process.
  67          *  - ABSTAIN: These $reqs are not handled. Some other primary provider may handle it.
  68          *  - UI: The $reqs are accepted, no other primary provider will run.
  69          *    Additional AuthenticationRequests are needed to complete the process.
  70          *  - REDIRECT: The $reqs are accepted, no other primary provider will run.
  71          *    Redirection to a third party is needed to complete the process.
  72          */
  73         public function beginPrimaryAuthentication( array $reqs );
  74
  75         /**
  76          * Continue an authentication flow
  77          * @param AuthenticationRequest[] $reqs
  78          * @return AuthenticationResponse Expected responses:
  79          *  - PASS: The user is authenticated. Secondary providers will now run.
  80          *  - FAIL: The user is not authenticated. Fail the authentication process.
  81          *  - UI: Additional AuthenticationRequests are needed to complete the process.
  82          *  - REDIRECT: Redirection to a third party is needed to complete the process.
  83          */
  84         public function continuePrimaryAuthentication( array $reqs );
  85
  86         /**
  87          * Post-login callback
  88          * @param User|null $user User that was attempted to be logged in, if known.
  89          *   This may become a "UserValue" in the future, or User may be refactored
  90          *   into such.
  91          * @param AuthenticationResponse $response Authentication response that will be returned
  92          */
  93         public function postAuthentication( $user, AuthenticationResponse $response );
  94
  95         /**
  96          * Test whether the named user exists
  97          * @param string $username
  98          * @param int $flags Bitfield of User:READ_* constants
  99          * @return bool
 100          */
 101         public function testUserExists( $username, $flags = User::READ_NORMAL );
 102
 103         /**
 104          * Test whether the named user can authenticate with this provider
 105          * @param string $username
 106          * @return bool
 107          */
 108         public function testUserCanAuthenticate( $username );
 109
 110         /**
 111          * Normalize the username for authentication
 112          *
 113          * Any two inputs that would result in the same user being authenticated
 114          * should return the same string here, while inputs that would result in
 115          * different users should return different strings.
 116          *
 117          * If possible, the best thing to do here is to return the canonicalized
 118          * name of the local user account that would be used. If not, return
 119          * something that would be invalid as a local username (e.g. wrap an email
 120          * address in "<>", or append "#servicename" to the username passed to a
 121          * third-party service).
 122          *
 123          * If the provider doesn't use a username at all in its
 124          * AuthenticationRequests, return null. If the name is syntactically
 125          * invalid, it's probably best to return null.
 126          *
 127          * @param string $username
 128          * @return string|null
 129          */
 130         public function providerNormalizeUsername( $username );
 131
 132         /**
 133          * Revoke the user's credentials
 134          *
 135          * This may cause the user to no longer exist for the provider, or the user
 136          * may continue to exist in a "disabled" state.
 137          *
 138          * The intention is that the named account will never again be usable for
 139          * normal login (i.e. there is no way to undo the revocation of access).
 140          *
 141          * @param string $username
 142          */
 143         public function providerRevokeAccessForUser( $username );
 144
 145         /**
 146          * Determine whether a property can change
 147          * @see AuthManager::allowsPropertyChange()
 148          * @param string $property
 149          * @return bool
 150          */
 151         public function providerAllowsPropertyChange( $property );
 152
 153         /**
 154          * Validate a change of authentication data (e.g. passwords)
 155          *
 156          * Return StatusValue::newGood( 'ignored' ) if you don't support this
 157          * AuthenticationRequest type.
 158          *
 159          * @param AuthenticationRequest $req
 160          * @param bool $checkData If false, $req hasn't been loaded from the
 161          *  submission so checks on user-submitted fields should be skipped.
 162          *  $req->username is considered user-submitted for this purpose, even
 163          *  if it cannot be changed via $req->loadFromSubmission.
 164          * @return StatusValue
 165          */
 166         public function providerAllowsAuthenticationDataChange(
 167                 AuthenticationRequest $req, $checkData = true
 168         );
 169
 170         /**
 171          * Change or remove authentication data (e.g. passwords)
 172          *
 173          * If $req was returned for AuthManager::ACTION_CHANGE, the corresponding
 174          * credentials should result in a successful login in the future.
 175          *
 176          * If $req was returned for AuthManager::ACTION_REMOVE, the corresponding
 177          * credentials should no longer result in a successful login.
 178          *
 179          * @param AuthenticationRequest $req
 180          */
 181         public function providerChangeAuthenticationData( AuthenticationRequest $req );
 182
 183         /**
 184          * Fetch the account-creation type
 185          * @return string One of the TYPE_* constants
 186          */
 187         public function accountCreationType();
 188
 189         /**
 190          * Determine whether an account creation may begin
 191          *
 192          * Called from AuthManager::beginAccountCreation()
 193          *
 194          * @note No need to test if the account exists, AuthManager checks that
 195          * @param User $user User being created (not added to the database yet).
 196          *   This may become a "UserValue" in the future, or User may be refactored
 197          *   into such.
 198          * @param User $creator User doing the creation. This may become a
 199          *   "UserValue" in the future, or User may be refactored into such.
 200          * @param AuthenticationRequest[] $reqs
 201          * @return StatusValue
 202          */
 203         public function testForAccountCreation( $user, $creator, array $reqs );
 204
 205         /**
 206          * Start an account creation flow
 207          * @param User $user User being created (not added to the database yet).
 208          *   This may become a "UserValue" in the future, or User may be refactored
 209          *   into such.
 210          * @param User $creator User doing the creation. This may become a
 211          *   "UserValue" in the future, or User may be refactored into such.
 212          * @param AuthenticationRequest[] $reqs
 213          * @return AuthenticationResponse Expected responses:
 214          *  - PASS: The user may be created. Secondary providers will now run.
 215          *  - FAIL: The user may not be created. Fail the creation process.
 216          *  - ABSTAIN: These $reqs are not handled. Some other primary provider may handle it.
 217          *  - UI: The $reqs are accepted, no other primary provider will run.
 218          *    Additional AuthenticationRequests are needed to complete the process.
 219          *  - REDIRECT: The $reqs are accepted, no other primary provider will run.
 220          *    Redirection to a third party is needed to complete the process.
 221          */
 222         public function beginPrimaryAccountCreation( $user, $creator, array $reqs );
 223
 224         /**
 225          * Continue an account creation flow
 226          * @param User $user User being created (not added to the database yet).
 227          *   This may become a "UserValue" in the future, or User may be refactored
 228          *   into such.
 229          * @param User $creator User doing the creation. This may become a
 230          *   "UserValue" in the future, or User may be refactored into such.
 231          * @param AuthenticationRequest[] $reqs
 232          * @return AuthenticationResponse Expected responses:
 233          *  - PASS: The user may be created. Secondary providers will now run.
 234          *  - FAIL: The user may not be created. Fail the creation process.
 235          *  - UI: Additional AuthenticationRequests are needed to complete the process.
 236          *  - REDIRECT: Redirection to a third party is needed to complete the process.
 237          */
 238         public function continuePrimaryAccountCreation( $user, $creator, array $reqs );
 239
 240         /**
 241          * Post-creation callback
 242          *
 243          * Called after the user is added to the database, before secondary
 244          * authentication providers are run.
 245          *
 246          * @param User $user User being created (has been added to the database now).
 247          *   This may become a "UserValue" in the future, or User may be refactored
 248          *   into such.
 249          * @param User $creator User doing the creation. This may become a
 250          *   "UserValue" in the future, or User may be refactored into such.
 251          * @param AuthenticationResponse $response PASS response returned earlier
 252          * @return string|null 'newusers' log subtype to use for logging the
 253          *   account creation. If null, either 'create' or 'create2' will be used
 254          *   depending on $creator.
 255          */
 256         public function finishAccountCreation( $user, $creator, AuthenticationResponse $response );
 257
 258         /**
 259          * Post-creation callback
 260          *
 261          * Called when the account creation process ends.
 262          *
 263          * @param User $user User that was attempted to be created.
 264          *   This may become a "UserValue" in the future, or User may be refactored
 265          *   into such.
 266          * @param User $creator User doing the creation. This may become a
 267          *   "UserValue" in the future, or User may be refactored into such.
 268          * @param AuthenticationResponse $response Authentication response that will be returned
 269          */
 270         public function postAccountCreation( $user, $creator, AuthenticationResponse $response );
 271
 272         /**
 273          * Determine whether an account may be created
 274          *
 275          * @param User $user User being created (not added to the database yet).
 276          *   This may become a "UserValue" in the future, or User may be refactored
 277          *   into such.
 278          * @param bool|string $autocreate False if this is not an auto-creation, or
 279          *  the source of the auto-creation passed to AuthManager::autoCreateUser().
 280          * @param array $options
 281          *  - flags: (int) Bitfield of User:READ_* constants, default User::READ_NORMAL
 282          *  - creating: (bool) If false (or missing), this call is only testing if
 283          *    a user could be created. If set, this (non-autocreation) is for
 284          *    actually creating an account and will be followed by a call to
 285          *    testForAccountCreation(). In this case, the provider might return
 286          *    StatusValue::newGood() here and let the later call to
 287          *    testForAccountCreation() do a more thorough test.
 288          * @return StatusValue
 289          */
 290         public function testUserForCreation( $user, $autocreate, array $options = [] );
 291
 292         /**
 293          * Post-auto-creation callback
 294          * @param User $user User being created (has been added to the database now).
 295          *   This may become a "UserValue" in the future, or User may be refactored
 296          *   into such.
 297          * @param string $source The source of the auto-creation passed to
 298          *  AuthManager::autoCreateUser().
 299          */
 300         public function autoCreatedAccount( $user, $source );
 301
 302         /**
 303          * Start linking an account to an existing user
 304          * @param User $user User being linked.
 305          *   This may become a "UserValue" in the future, or User may be refactored
 306          *   into such.
 307          * @param AuthenticationRequest[] $reqs
 308          * @return AuthenticationResponse Expected responses:
 309          *  - PASS: The user is linked.
 310          *  - FAIL: The user is not linked. Fail the linking process.
 311          *  - ABSTAIN: These $reqs are not handled. Some other primary provider may handle it.
 312          *  - UI: The $reqs are accepted, no other primary provider will run.
 313          *    Additional AuthenticationRequests are needed to complete the process.
 314          *  - REDIRECT: The $reqs are accepted, no other primary provider will run.
 315          *    Redirection to a third party is needed to complete the process.
 316          */
 317         public function beginPrimaryAccountLink( $user, array $reqs );
 318
 319         /**
 320          * Continue linking an account to an existing user
 321          * @param User $user User being linked.
 322          *   This may become a "UserValue" in the future, or User may be refactored
 323          *   into such.
 324          * @param AuthenticationRequest[] $reqs
 325          * @return AuthenticationResponse Expected responses:
 326          *  - PASS: The user is linked.
 327          *  - FAIL: The user is not linked. Fail the linking process.
 328          *  - UI: Additional AuthenticationRequests are needed to complete the process.
 329          *  - REDIRECT: Redirection to a third party is needed to complete the process.
 330          */
 331         public function continuePrimaryAccountLink( $user, array $reqs );
 332
 333         /**
 334          * Post-link callback
 335          * @param User $user User that was attempted to be linked.
 336          *   This may become a "UserValue" in the future, or User may be refactored
 337          *   into such.
 338          * @param AuthenticationResponse $response Authentication response that will be returned
 339          */
 340         public function postAccountLink( $user, AuthenticationResponse $response );
 341
 342 }