Repository navigation
Add a cooldown for reset password emails - #55308
Open
gaoyikeshuer wants to merge 1 commit into
Open
gaoyikeshuer wants to merge 1 commit into
gaoyikeshuer wants to merge 1 commit into
Conversation
gaoyikeshuer
force-pushed
the
reset-email-cooldown-55244
branch
from
November 18, 2026 14:37
c405a3e to
d33371d
Compare
gaoyikeshuer
marked this pull request as ready for review
November 18, 2026 14:43
Contributor
There was a problem hiding this comment.
🟢 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
force-pushed
the
reset-email-cooldown-55244
branch
from
November 19, 2026 11:20
d33371d to
4eaea57
Compare
Closes keycloak#55244 Signed-off-by: Yike Gao <yikegao8@gmail.com>
gaoyikeshuer
force-pushed
the
reset-email-cooldown-55244
branch
from
November 19, 2026 12:44
4eaea57 to
dd67795
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_ERRORevent with the errorslow_down, so admins can still see it.The cooldown is checked and started in one
putIfAbsentcall, 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
0in 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