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