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