Repository navigation
Add a cooldown for reset password emails - #55308
gaoyikeshuer wants to merge 1 commit into
Conversation
c405a3e to
d33371d
Compare
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
d33371d to
4eaea57
Compare
4eaea57 to
dd67795
Compare
mabartos
left a comment
There was a problem hiding this comment.
@gaoyikeshuer Thanks! Just one thing, otherwise LGTM.
| .name(EmailCooldownManager.EMAIL_RESEND_COOLDOWN_SECONDS) | ||
| .label("Cooldown between reset emails (seconds)") | ||
| .helpText("Minimum delay in seconds before another reset email is sent to the same user. Set it to 0 to send an email for every request.") | ||
| .type(ProviderConfigProperty.STRING_TYPE) |
There was a problem hiding this comment.
| .type(ProviderConfigProperty.STRING_TYPE) | |
| .type(ProviderConfigProperty.INTEGER_TYPE) |
Any specific reason why it's String?
There was a problem hiding this comment.
Thanks @mabartos it's done now. acutally there is no specific reason behind it. I just kept it the same as existing cooldown porperty in 'EmailCooldownManager.createCooldownConfigProperty()' that verify-email and update-email use which is also string_type
Closes keycloak#55244 Signed-off-by: Yike Gao <yikegao8@gmail.com>
dd67795 to
d1ee405
Compare

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