Password recovery

This page helps you let users set a new password when they forget theirs, without an administrator’s help.

Password recovery works by email: the user asks for a link, and the link opens a form where they choose a new password. It needs email set up, and an email address the auth server knows is theirs. With email off, the sign-in page shows no Forgot password? link, and /forgot-password answers 404.

Let users recover their password

1. Set up email under Admin, Email - SMTP, and send yourself a test message from the Send test email tab. The sign-in page now shows Forgot password?.

2. Make sure your users’ email addresses are verified. A user’s Email tab shows it as Email verified, and users can verify their own under Account, Email verification.

That’s all. A user who clicks Forgot password? enters their email address and gets a link to set a new password.

When something goes wrong, see A user cannot reset their password.

Who gets a link

The link is sent only when the address belongs to a user who is enabled and whose address is verified. For any other address, one with no account, an unverified one, or a disabled user’s, nothing is sent and no link is made.

Whatever happened, the page says the same thing: “If you’re a registered user, a password reset link has been sent to your email address.” That way the form can’t be used to find out which addresses have an account. The reason stays in the audit log, as the outcome of the requested_password_reset entry, which records the address only as a digest.

Caution

Users who registered without email verification, and users an administrator created without turning on Email verified, start with an unverified address, so they can’t recover a password on their own until it’s verified. They can verify it under Account, Email verification, which appears whenever email is set up, or an administrator can mark it verified or set a new password for them.

The link

A reset link works once. It must be followed within 5 minutes of being sent, and the form it opens must then be sent within 5 more. It stops working when:

• it’s been used;
• the user asked for another one, which replaces it;
• the user was disabled;
• the user’s email address was changed, by the user or by an administrator, since the link belongs to the address it was sent to.

A dead link shows “Unable to set the password. The verification code appears to be invalid or expired.” and the user asks for a new one. Each refusal leaves a failed_reset_password_code entry in the audit log, whose reason narrows it down: code_expired for a link past its lifetime, marker_expired for a form sent more than 5 minutes after the link was followed, account_disabled for a disabled user, and unknown_code for a link that was used, replaced by a newer one, or retired by an address change, which it can’t tell apart.

The new password must meet the Password policy under Admin, General.

What a reset does

Setting a new password from the link ends every session the user has and revokes their refresh tokens, so every client must sign them in again. Whoever reset the password isn’t necessarily whoever holds those sessions, which is the point when a laptop is stolen. The audit log records it as revoked_user_auth_state, with the reason password_reset. See credential changes.

The link an administrator sends

When you create a user and choose Email the user a link to set up their password, the user gets this same kind of link, except that it works for 24 hours, since they read it when they read their mail. Any link to an account that has no password yet lasts 24 hours. It works even though the address isn’t verified yet, since an administrator chose to send it there.

If it expires unused, the user can’t ask for another with Forgot password?, which sends nothing to an unverified address, and nothing sends the setup link again. Turn on Email verified on the user’s Email tab so they can, or set their password yourself on the Authentication tab.

Setting the password through it also marks the address verified, since following the link proved it’s theirs, and leaves a verified_email entry in the audit log.

If you typed the address wrong, correcting it retires the link that went to the wrong address. Open the user’s Authentication tab and use Set password instead, or have the user ask for a reset link once their address is verified.

Limits

An address can ask for 5 links every 5 minutes, whether or not the rate limiter is on. With it on, an IP address can ask for 20, and following links and sending the form is limited to 30 every 5 minutes per IP address. Past that, the page shows “Too many attempts”: see Too many attempts or 429.

Next steps

A user cannot reset their passwordWhat stops a reset, and how to fix it.

Self-registrationLet people create their own accounts.