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 your password? link, and /forgot-password answers 404.

Let users recover their password

1. Set up email under Admin, Email, and send yourself a test message from the Send test email tab. The sign-in page now shows Forgot your 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 your 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 an account uses this address, we’ve sent it a link to reset your password”. 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 “This link can’t be used”, 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, which the form shows under the field.

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 a link to set it, 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 your 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 New 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.