3 * User password reset helper for MediaWiki.
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.
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.
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
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
;
35 * Helper class for the password reset functionality shared by the web UI and the API.
37 * Requires the TemporaryPasswordPrimaryAuthenticationProvider and the
38 * EmailNotificationSecondaryAuthenticationProvider (or something providing equivalent
39 * functionality) to be enabled.
41 class PasswordReset
implements LoggerAwareInterface
{
44 /** @var ServiceOptions|Config */
47 /** @var AuthManager */
48 protected $authManager;
50 /** @var PermissionManager */
51 protected $permissionManager;
53 /** @var ILoadBalancer */
54 protected $loadBalancer;
57 * In-process cache for isAllowed lookups, by username.
58 * Contains a StatusValue object
61 private $permissionCache;
63 public const CONSTRUCTOR_OPTIONS
= [
64 'AllowRequiringEmailForResets',
66 'PasswordResetRoutes',
70 * This class is managed by MediaWikiServices, don't instantiate directly.
72 * @param ServiceOptions|Config $config
73 * @param AuthManager $authManager
74 * @param PermissionManager $permissionManager
75 * @param ILoadBalancer|null $loadBalancer
76 * @param LoggerInterface|null $logger
78 public function __construct(
80 AuthManager
$authManager,
81 PermissionManager
$permissionManager,
82 ILoadBalancer
$loadBalancer = null,
83 LoggerInterface
$logger = null
85 $this->config
= $config;
86 $this->authManager
= $authManager;
87 $this->permissionManager
= $permissionManager;
89 if ( !$loadBalancer ) {
90 wfDeprecated( 'Not passing LoadBalancer to ' . __METHOD__
, '1.34' );
91 $loadBalancer = MediaWikiServices
::getInstance()->getDBLoadBalancer();
93 $this->loadBalancer
= $loadBalancer;
96 wfDeprecated( 'Not passing LoggerInterface to ' . __METHOD__
, '1.34' );
97 $logger = LoggerFactory
::getInstance( 'authentication' );
99 $this->logger
= $logger;
101 $this->permissionCache
= new MapCacheLRU( 1 );
105 * Check if a given user has permission to use this functionality.
107 * @since 1.29 Second argument for displayPassword removed.
108 * @return StatusValue
110 public function isAllowed( User
$user ) {
111 $status = $this->permissionCache
->get( $user->getName() );
113 $resetRoutes = $this->config
->get( 'PasswordResetRoutes' );
114 $status = StatusValue
::newGood();
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' );
120 ( $providerStatus = $this->authManager
->allowsAuthenticationDataChange(
121 new TemporaryPasswordAuthenticationRequest(), false ) )
122 && !$providerStatus->isGood()
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' );
140 $this->permissionCache
->set( $user->getName(), $status );
147 * Do a password reset. Authorization is the caller's responsibility.
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.
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
161 public function execute(
162 User
$performingUser, $username = null, $email = null
164 if ( !$this->isAllowed( $performingUser )->isGood() ) {
165 throw new LogicException( 'User ' . $performingUser->getName()
166 . ' is not allowed to reset passwords' );
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();
175 $username = $username ??
'';
176 $email = $email ??
'';
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();
188 // Only email was provided
190 $users = $this->getUsersByEmail( $email );
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] );
201 // The user didn't supply any data
202 return StatusValue
::newFatal( 'passwordreset-nodata' );
205 // Check for hooks (captcha etc), and allow them to modify the users list
208 'Username' => $username,
209 // Email gets set to null for backward compatibility
210 'Email' => $method === 'email' ?
$email : null,
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 );
218 if ( !Hooks
::run( 'SpecialPasswordResetOnSubmit', [ &$users, $data, &$error ] ) ) {
219 return StatusValue
::newFatal( Message
::newFromSpecifier( $error ) );
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;
226 $requireEmail = $this->config
->get( 'AllowRequiringEmailForResets' )
227 && $method === 'username'
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();
236 if ( $method === 'email' ) {
237 // Don't reveal whether or not an email address is in use
238 return StatusValue
::newGood();
240 return StatusValue
::newFatal( 'noname' );
244 // If the username is not valid, tell the user.
245 if ( $username && !User
::getCanonicalName( $username ) ) {
246 return StatusValue
::newFatal( 'noname' );
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();
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();
263 // Email is required but the email doesn't match: pretend everything's fine.
264 if ( $requireEmail && $firstUser->getEmail() !== $email ) {
265 return StatusValue
::newGood();
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();
272 return StatusValue
::newFatal( 'badipaddress' );
275 Hooks
::run( 'User::mailPasswordInternal', [ &$performingUser, &$ip, &$firstUser ] );
277 $result = StatusValue
::newGood();
279 foreach ( $users as $user ) {
280 $req = TemporaryPasswordAuthenticationRequest
::newRandom();
281 $req->username
= $user->getName();
282 $req->mailpassword
= true;
283 $req->caller
= $performingUser->getName();
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();
293 if ( $status->isGood() && $status->getValue() !== 'ignored' ) {
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' );
301 $result->merge( $status );
306 'requestingIp' => $ip,
307 'requestingUser' => $performingUser->getName(),
308 'targetUsername' => $username,
309 'targetEmail' => $email,
312 if ( !$result->isGood() ) {
314 "{requestingUser} attempted password reset of {actualUser} but failed",
315 $logContext +
[ 'errors' => $result->getErrors() ]
320 DeferredUpdates
::addUpdate(
321 new SendPasswordResetEmailUpdate( $this->authManager
, $reqs, $logContext ),
322 DeferredUpdates
::POSTSEND
325 return StatusValue
::newGood();
329 * Check whether the user is blocked.
330 * Ignores certain types of system blocks that are only meant to force users to log in.
335 protected function isBlocked( User
$user ) {
336 $block = $user->getBlock() ?
: $user->getGlobalBlock();
340 return $block->appliesToPasswordReset();
344 * @param string $email
346 * @throws MWException On unexpected database errors
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 ],
360 // Some sort of database error, probably unreachable
361 throw new MWException( 'Unknown database error in ' . __METHOD__
);
365 foreach ( $res as $row ) {
366 $users[] = User
::newFromRow( $row );
372 * User object creation helper for testability
373 * @codeCoverageIgnore
375 * @param string $username
378 protected function lookupUser( $username ) {
379 return User
::newFromName( $username );