includes/user/PasswordReset.php

   1 <?php
   2 /**
   3  * User password reset helper for MediaWiki.
   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  */
  22
  23 use MediaWiki\Auth\AuthManager;
  24 use MediaWiki\Auth\TemporaryPasswordAuthenticationRequest;
  25 use MediaWiki\Config\ServiceOptions;
  26 use MediaWiki\Logger\LoggerFactory;
  27 use MediaWiki\MediaWikiServices;
  28 use MediaWiki\Permissions\PermissionManager;
  29 use Psr\Log\LoggerAwareInterface;
  30 use Psr\Log\LoggerAwareTrait;
  31 use Psr\Log\LoggerInterface;
  32 use Wikimedia\Rdbms\ILoadBalancer;
  33
  34 /**
  35  * Helper class for the password reset functionality shared by the web UI and the API.
  36  *
  37  * Requires the TemporaryPasswordPrimaryAuthenticationProvider and the
  38  * EmailNotificationSecondaryAuthenticationProvider (or something providing equivalent
  39  * functionality) to be enabled.
  40  */
  41 class PasswordReset implements LoggerAwareInterface {
  42         use LoggerAwareTrait;
  43
  44         /** @var ServiceOptions|Config */
  45         protected $config;
  46
  47         /** @var AuthManager */
  48         protected $authManager;
  49
  50         /** @var PermissionManager */
  51         protected $permissionManager;
  52
  53         /** @var ILoadBalancer */
  54         protected $loadBalancer;
  55
  56         /**
  57          * In-process cache for isAllowed lookups, by username.
  58          * Contains a StatusValue object
  59          * @var MapCacheLRU
  60          */
  61         private $permissionCache;
  62
  63         public const CONSTRUCTOR_OPTIONS = [
  64                 'AllowRequiringEmailForResets',
  65                 'EnableEmail',
  66                 'PasswordResetRoutes',
  67         ];
  68
  69         /**
  70          * This class is managed by MediaWikiServices, don't instantiate directly.
  71          *
  72          * @param ServiceOptions|Config $config
  73          * @param AuthManager $authManager
  74          * @param PermissionManager $permissionManager
  75          * @param ILoadBalancer|null $loadBalancer
  76          * @param LoggerInterface|null $logger
  77          */
  78         public function __construct(
  79                 $config,
  80                 AuthManager $authManager,
  81                 PermissionManager $permissionManager,
  82                 ILoadBalancer $loadBalancer = null,
  83                 LoggerInterface $logger = null
  84         ) {
  85                 $this->config = $config;
  86                 $this->authManager = $authManager;
  87                 $this->permissionManager = $permissionManager;
  88
  89                 if ( !$loadBalancer ) {
  90                         wfDeprecated( 'Not passing LoadBalancer to ' . __METHOD__, '1.34' );
  91                         $loadBalancer = MediaWikiServices::getInstance()->getDBLoadBalancer();
  92                 }
  93                 $this->loadBalancer = $loadBalancer;
  94
  95                 if ( !$logger ) {
  96                         wfDeprecated( 'Not passing LoggerInterface to ' . __METHOD__, '1.34' );
  97                         $logger = LoggerFactory::getInstance( 'authentication' );
  98                 }
  99                 $this->logger = $logger;
 100
 101                 $this->permissionCache = new MapCacheLRU( 1 );
 102         }
 103
 104         /**
 105          * Check if a given user has permission to use this functionality.
 106          * @param User $user
 107          * @since 1.29 Second argument for displayPassword removed.
 108          * @return StatusValue
 109          */
 110         public function isAllowed( User $user ) {
 111                 $status = $this->permissionCache->get( $user->getName() );
 112                 if ( !$status ) {
 113                         $resetRoutes = $this->config->get( 'PasswordResetRoutes' );
 114                         $status = StatusValue::newGood();
 115
 116                         if ( !is_array( $resetRoutes ) || !in_array( true, $resetRoutes, true ) ) {
 117                                 // Maybe password resets are disabled, or there are no allowable routes
 118                                 $status = StatusValue::newFatal( 'passwordreset-disabled' );
 119                         } elseif (
 120                                 ( $providerStatus = $this->authManager->allowsAuthenticationDataChange(
 121                                         new TemporaryPasswordAuthenticationRequest(), false ) )
 122                                 && !$providerStatus->isGood()
 123                         ) {
 124                                 // Maybe the external auth plugin won't allow local password changes
 125                                 $status = StatusValue::newFatal( 'resetpass_forbidden-reason',
 126                                         $providerStatus->getMessage() );
 127                         } elseif ( !$this->config->get( 'EnableEmail' ) ) {
 128                                 // Maybe email features have been disabled
 129                                 $status = StatusValue::newFatal( 'passwordreset-emaildisabled' );
 130                         } elseif ( !$this->permissionManager->userHasRight( $user, 'editmyprivateinfo' ) ) {
 131                                 // Maybe not all users have permission to change private data
 132                                 $status = StatusValue::newFatal( 'badaccess' );
 133                         } elseif ( $this->isBlocked( $user ) ) {
 134                                 // Maybe the user is blocked (check this here rather than relying on the parent
 135                                 // method as we have a more specific error message to use here and we want to
 136                                 // ignore some types of blocks)
 137                                 $status = StatusValue::newFatal( 'blocked-mailpassword' );
 138                         }
 139
 140                         $this->permissionCache->set( $user->getName(), $status );
 141                 }
 142
 143                 return $status;
 144         }
 145
 146         /**
 147          * Do a password reset. Authorization is the caller's responsibility.
 148          *
 149          * Process the form.  At this point we know that the user passes all the criteria in
 150          * userCanExecute(), and if the data array contains 'Username', etc, then Username
 151          * resets are allowed.
 152          *
 153          * @since 1.29 Fourth argument for displayPassword removed.
 154          * @param User $performingUser The user that does the password reset
 155          * @param string|null $username The user whose password is reset
 156          * @param string|null $email Alternative way to specify the user
 157          * @return StatusValue
 158          * @throws LogicException When the user is not allowed to perform the action
 159          * @throws MWException On unexpected DB errors
 160          */
 161         public function execute(
 162                 User $performingUser, $username = null, $email = null
 163         ) {
 164                 if ( !$this->isAllowed( $performingUser )->isGood() ) {
 165                         throw new LogicException( 'User ' . $performingUser->getName()
 166                                 . ' is not allowed to reset passwords' );
 167                 }
 168
 169                 // Check against the rate limiter. If the $wgRateLimit is reached, we want to pretend
 170                 // that the request was good to avoid displaying an error message.
 171                 if ( $performingUser->pingLimiter( 'mailpassword' ) ) {
 172                         return StatusValue::newGood();
 173                 }
 174
 175                 $username = $username ?? '';
 176                 $email = $email ?? '';
 177
 178                 $resetRoutes = $this->config->get( 'PasswordResetRoutes' )
 179                         + [ 'username' => false, 'email' => false ];
 180                 if ( $resetRoutes['username'] && $username ) {
 181                         $method = 'username';
 182                         $users = [ $this->lookupUser( $username ) ];
 183                 } elseif ( $resetRoutes['email'] && $email ) {
 184                         if ( !Sanitizer::validateEmail( $email ) ) {
 185                                 // Only email was supplied but not valid: pretend everything's fine.
 186                                 return StatusValue::newGood();
 187                         }
 188                         // Only email was provided
 189                         $method = 'email';
 190                         $users = $this->getUsersByEmail( $email );
 191                         $username = null;
 192                         // Remove users whose preference 'requireemail' is on since username was not submitted
 193                         if ( $this->config->get( 'AllowRequiringEmailForResets' ) ) {
 194                                 foreach ( $users as $index => $user ) {
 195                                         if ( $user->getBoolOption( 'requireemail' ) ) {
 196                                                 unset( $users[$index] );
 197                                         }
 198                                 }
 199                         }
 200                 } else {
 201                         // The user didn't supply any data
 202                         return StatusValue::newFatal( 'passwordreset-nodata' );
 203                 }
 204
 205                 // Check for hooks (captcha etc), and allow them to modify the users list
 206                 $error = [];
 207                 $data = [
 208                         'Username' => $username,
 209                         // Email gets set to null for backward compatibility
 210                         'Email' => $method === 'email' ? $email : null,
 211                 ];
 212
 213                 // Recreate the $users array with its values so that we reset the numeric keys since
 214                 // the key '0' might have been unset from $users array. 'SpecialPasswordResetOnSubmit'
 215                 // hook assumes that index '0' is defined if $users is not empty.
 216                 $users = array_values( $users );
 217
 218                 if ( !Hooks::run( 'SpecialPasswordResetOnSubmit', [ &$users, $data, &$error ] ) ) {
 219                         return StatusValue::newFatal( Message::newFromSpecifier( $error ) );
 220                 }
 221
 222                 // Get the first element in $users by using `reset` function just in case $users is changed
 223                 // in 'SpecialPasswordResetOnSubmit' hook.
 224                 $firstUser = reset( $users ) ?? null;
 225
 226                 $requireEmail = $this->config->get( 'AllowRequiringEmailForResets' )
 227                         && $method === 'username'
 228                         && $firstUser
 229                         && $firstUser->getBoolOption( 'requireemail' );
 230                 if ( $requireEmail && ( $email === '' || !Sanitizer::validateEmail( $email ) ) ) {
 231                         // Email is required, and not supplied or not valid: pretend everything's fine.
 232                         return StatusValue::newGood();
 233                 }
 234
 235                 if ( !$users ) {
 236                         if ( $method === 'email' ) {
 237                                 // Don't reveal whether or not an email address is in use
 238                                 return StatusValue::newGood();
 239                         } else {
 240                                 return StatusValue::newFatal( 'noname' );
 241                         }
 242                 }
 243
 244                 // If the username is not valid, tell the user.
 245                 if ( $username && !User::getCanonicalName( $username ) ) {
 246                         return StatusValue::newFatal( 'noname' );
 247                 }
 248
 249                 // If the username doesn't exist, don't tell the user.
 250                 // This is not to avoid disclosure, as this information is available elsewhere,
 251                 // but it simplifies the password reset UX. T238961.
 252                 if ( !$firstUser instanceof User || !$firstUser->getId() ) {
 253                         return StatusValue::newGood();
 254                 }
 255
 256                 // The user doesn't have an email address, but pretend everything's fine to avoid
 257                 // disclosing this fact. Note that all the users will have the same email address (or none),
 258                 // so there's no need to check more than the first.
 259                 if ( !$firstUser->getEmail() ) {
 260                         return StatusValue::newGood();
 261                 }
 262
 263                 // Email is required but the email doesn't match: pretend everything's fine.
 264                 if ( $requireEmail && $firstUser->getEmail() !== $email ) {
 265                         return StatusValue::newGood();
 266                 }
 267
 268                 // We need to have a valid IP address for the hook, but per T20347, we should
 269                 // send the user's name if they're logged in.
 270                 $ip = $performingUser->getRequest()->getIP();
 271                 if ( !$ip ) {
 272                         return StatusValue::newFatal( 'badipaddress' );
 273                 }
 274
 275                 Hooks::run( 'User::mailPasswordInternal', [ &$performingUser, &$ip, &$firstUser ] );
 276
 277                 $result = StatusValue::newGood();
 278                 $reqs = [];
 279                 foreach ( $users as $user ) {
 280                         $req = TemporaryPasswordAuthenticationRequest::newRandom();
 281                         $req->username = $user->getName();
 282                         $req->mailpassword = true;
 283                         $req->caller = $performingUser->getName();
 284
 285                         $status = $this->authManager->allowsAuthenticationDataChange( $req, true );
 286                         // If status is good and the value is 'throttled-mailpassword', we want to pretend
 287                         // that the request was good to avoid displaying an error message and disclose
 288                         // if a reset password was previously sent.
 289                         if ( $status->isGood() && $status->getValue() === 'throttled-mailpassword' ) {
 290                                 return StatusValue::newGood();
 291                         }
 292
 293                         if ( $status->isGood() && $status->getValue() !== 'ignored' ) {
 294                                 $reqs[] = $req;
 295                         } elseif ( $result->isGood() ) {
 296                                 // only record the first error, to avoid exposing the number of users having the
 297                                 // same email address
 298                                 if ( $status->getValue() === 'ignored' ) {
 299                                         $status = StatusValue::newFatal( 'passwordreset-ignored' );
 300                                 }
 301                                 $result->merge( $status );
 302                         }
 303                 }
 304
 305                 $logContext = [
 306                         'requestingIp' => $ip,
 307                         'requestingUser' => $performingUser->getName(),
 308                         'targetUsername' => $username,
 309                         'targetEmail' => $email,
 310                 ];
 311
 312                 if ( !$result->isGood() ) {
 313                         $this->logger->info(
 314                                 "{requestingUser} attempted password reset of {actualUser} but failed",
 315                                 $logContext + [ 'errors' => $result->getErrors() ]
 316                         );
 317                         return $result;
 318                 }
 319
 320                 DeferredUpdates::addUpdate(
 321                         new SendPasswordResetEmailUpdate( $this->authManager, $reqs, $logContext ),
 322                         DeferredUpdates::POSTSEND
 323                 );
 324
 325                 return StatusValue::newGood();
 326         }
 327
 328         /**
 329          * Check whether the user is blocked.
 330          * Ignores certain types of system blocks that are only meant to force users to log in.
 331          * @param User $user
 332          * @return bool
 333          * @since 1.30
 334          */
 335         protected function isBlocked( User $user ) {
 336                 $block = $user->getBlock() ?: $user->getGlobalBlock();
 337                 if ( !$block ) {
 338                         return false;
 339                 }
 340                 return $block->appliesToPasswordReset();
 341         }
 342
 343         /**
 344          * @param string $email
 345          * @return User[]
 346          * @throws MWException On unexpected database errors
 347          */
 348         protected function getUsersByEmail( $email ) {
 349                 $userQuery = User::getQueryInfo();
 350                 $res = $this->loadBalancer->getConnectionRef( DB_REPLICA )->select(
 351                         $userQuery['tables'],
 352                         $userQuery['fields'],
 353                         [ 'user_email' => $email ],
 354                         __METHOD__,
 355                         [],
 356                         $userQuery['joins']
 357                 );
 358
 359                 if ( !$res ) {
 360                         // Some sort of database error, probably unreachable
 361                         throw new MWException( 'Unknown database error in ' . __METHOD__ );
 362                 }
 363
 364                 $users = [];
 365                 foreach ( $res as $row ) {
 366                         $users[] = User::newFromRow( $row );
 367                 }
 368                 return $users;
 369         }
 370
 371         /**
 372          * User object creation helper for testability
 373          * @codeCoverageIgnore
 374          *
 375          * @param string $username
 376          * @return User|false
 377          */
 378         protected function lookupUser( $username ) {
 379                 return User::newFromName( $username );
 380         }
 381 }