Skip to content

Add a cooldown for reset password emails - #55308

Open
gaoyikeshuer wants to merge 1 commit into
keycloak:mainfrom
gaoyikeshuer:reset-email-cooldown-55244
Open

gaoyikeshuer wants to merge 1 commit into
keycloak:mainfrom
gaoyikeshuer:reset-email-cooldown-55244

Conversation

@gaoyikeshuer

@gaoyikeshuer gaoyikeshuer commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

The form shows the same page during the cooldown, with no "please wait" message. The form is anonymous, so a visible message would show whether an account exists. A suppressed request records a SEND_RESET_PASSWORD_ERROR event with the error slow_down, so admins can still see it.

The cooldown is checked and started in one putIfAbsent call, because anonymous requests can be sent in parallel and the existing check-then-add methods leave a gap. The verify-email and update-email paths are not changed.

The default is 30 seconds, the same as verify-email and update-email, and 0 in the Send Reset Email step turns it off. Someone who knows a username can keep the cooldown running, but the email that was sent still contains a working link, so the user is not locked out.

The key uses a hash of the user ID, so it fits the database store for long federated IDs. Unknown usernames get their own key, so a repeated request does the same work whether or not the user exists (prevent enumeration). The verify-email and update-email keys have the same length limit and are left for a follow-up issue which maybe we need to open later.

After fix: [

Screen.Recording.2026-11-18.at.13.01.06.mov
Screen.Recording.2026-11-18.at.13.04.49.mov

](url)

Closes #55244

reference ticket: #43076

@gaoyikeshuer
gaoyikeshuer force-pushed the reset-email-cooldown-55244 branch from c405a3e to d33371d Compare November 18, 2026 14:37
@gaoyikeshuer
gaoyikeshuer marked this pull request as ready for review November 18, 2026 14:43
@gaoyikeshuer
gaoyikeshuer requested review from a team as code owners November 18, 2026 14:43
Copilot AI balanced review requested due to automatic review settings November 18, 2026 14:43

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the configurable password-reset email cooldown change.

No open issues 🎉

What changed in this PR

Adds a configurable per-user cooldown to Keycloak’s password-reset email flow, addressing #55244 by limiting inbox flooding while preserving the generic response that avoids revealing whether an account exists.

Changes:

  • Enforces a default 30-second cooldown with an atomic check, configurable duration, and an option to disable it.
  • Adds tests for suppression, expiration, disabled cooldowns, and invalid configuration; clears cooldown state in existing tests.
  • Documents the new behavior and configuration.
File Description
testsuite/​integration-arquillian/​tests/​base/​src/​test/​java/​org/​keycloak/​testsuite/​forms/​ResetPasswordTest.java Clears cooldowns before repeated reset requests.
testsuite/​integration-arquillian/​tests/​base/​src/​test/​java/​org/​keycloak/​testsuite/​federation/​ldap/​LDAPNoCacheTest.java Clears cooldowns between LDAP reset-email checks.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​sessionlimits/​UserSessionLimitsTest.java Resets cooldown state during test setup.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​i18n/​EmailTest.java Clears cooldowns for repeated email localization checks.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​forms/​ResetPasswordUserEnumerationTest.java Isolates cooldown state between enumeration test cases.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​forms/​ResetPasswordTest.java Tests cooldown behavior and updates email-count expectations.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​forms/​AbstractResetCredentialsAlternativeFlowsTest.java Clears shared-user cooldowns before alternative-flow tests.
services/​src/​main/​java/​org/​keycloak/​authentication/​requiredactions/​util/​EmailCooldownManager.java Adds atomic cooldown acquisition and authenticator configuration parsing.
services/​src/​main/​java/​org/​keycloak/​authentication/​authenticators/​resetcred/​ResetCredentialEmail.java Suppresses emails during cooldown and exposes configuration.
docs/​documentation/​upgrading/​topics/​changes/​changes-27_0_0.adoc Describes the default cooldown and related error event.
docs/​documentation/​server_admin/​topics/​login-settings/​forgot-password.adoc Explains cooldown settings for administrators.

Review effort: Balanced

@gaoyikeshuer
gaoyikeshuer force-pushed the reset-email-cooldown-55244 branch from d33371d to 4eaea57 Compare November 19, 2026 11:20
Copilot AI balanced review requested due to automatic review settings November 19, 2026 11:20

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The cooldown key can exceed the database’s 255-character limit for valid LDAP users in stateless mode, causing password resets to fail before any email is sent.

1 open issue

Review effort: Balanced

Closes keycloak#55244

Signed-off-by: Yike Gao <yikegao8@gmail.com>
@gaoyikeshuer
gaoyikeshuer force-pushed the reset-email-cooldown-55244 branch from 4eaea57 to dd67795 Compare November 19, 2026 12:44
Copilot AI balanced review requested due to automatic review settings November 19, 2026 12:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The password-reset email cooldown change has no active review issues requiring resolution.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Password reset email path lacks cooldown allowing anonymous inbox flooding

2 participants