keycloak~安全防护-暴力检查的支持

结合您提供的 Keycloak 14.0.0 截图，我先为您逐一解释这些安全防御（Brute Force Detection）配置项的作用，然后针对您的需求给出具体的配置方案。

一、配置项作用详解

1. Enabled (启用)：ON

   • 开启或关闭暴力破解检测功能。

2. Permanent Lockout (永久锁定)：OFF

   • 如果开启，当达到最大失败次数时，用户将被永久锁定，必须管理员手动解锁。
   • 当前为 OFF，表示采用临时锁定机制。

3. Max Login Failures (最大登录失败次数)：3

   • 允许连续登录失败的次数上限。达到此数值后，触发锁定机制。
   • 截图中的配置是 3 次。

4. Wait Increment (等待增量)：1 Minutes

   • 触发锁定后，每次达到失败上限时，增加的基础等待时间。
   • 注意：Keycloak 采用递增锁定策略。第一次触发锁定等待 1 分钟；如果在等待期内再次失败，等待时间会累加（如 2 分钟、3 分钟...），直到达到 Max Wait 上限。

5. Quick Login Check Milli Seconds (快速登录检查毫秒数)：1000

   • 用于检测脚本或自动化工具的快速尝试。如果两次登录失败的时间间隔小于 1000 毫秒（1秒），Keycloak 会判定为“快速登录”攻击。

6. Minimum Quick Login Wait (最小快速登录等待)：5 Minutes

   • 如果检测到“快速登录”（间隔小于上面的1000毫秒），则强制该用户等待 5 分钟，而不再走常规的递增逻辑。这主要用于防御高速撞库脚本。

7. Max Wait (最大等待时间)：2 Minutes

   • 临时锁定时间的上限。无论失败多少次，等待时间（Wait Increment 累加的结果）不会超过这个值。
   • 截图中的配置是 2 分钟（这意味着当前配置下，用户最多只会被锁定 2 分钟）。

8. Failure Reset Time (失败重置时间)：12 Hours

   • 记录失败次数的计数器在多少时间后自动清零。
   • 如果设置为 12 小时，意味着用户在这 12 小时内累计的失败次数会被保留。如果超过 12 小时没有新的失败，计数归零。

---

二、针对您的实例需求进行配置

您的需求是：“当一个人在1分钟之内登录失败5次，就临时锁定用户30分钟。”

在 Keycloak 原生机制中，无法直接设定严格的“1分钟滑动窗口”，但可以通过组合配置达到几乎相同的效果。

请在截图的界面上按照以下数值进行修改：

• Enabled: ON （保持开启）
• Permanent Lockout: OFF （保持关闭，确保是临时锁定）
• Max Login Failures: 5 （改为 5 次）
• Wait Increment: 30 Minutes （改为 30 分钟）
• Quick Login Check Milli Seconds: 1000 （保持默认即可，用于拦截极速脚本）
• Minimum Quick Login Wait: 1 Minutes （可酌情设置，只要拦截快速点击即可）
• Max Wait: 30 Minutes （改为 30 分钟，强制锁定上限为30分钟）
• Failure Reset Time: 1 Minutes （改为 1 分钟，这是实现“1分钟内”的关键）

💡 配置原理解释：

1. Max Login Failures = 5：满足失败5次触发。
2. Failure Reset Time = 1 Minutes：Keycloak 会在1分钟无失败操作后清空计数器。配合5次限制，这相当于实现了“在1分钟窗口期内累计失败5次”的逻辑（如果1分钟内没达到5次，之前的失败计数就会被清零）。
3. Wait Increment = 30 Minutes 且 Max Wait = 30 Minutes：因为 Keycloak 的锁定时间是递增的，为了防止第二次触发变成60分钟，将递增基础值设为30分钟，且最大值也限制为30分钟，这样无论触发多少次，每次的临时锁定时间都固定为30分钟。

---

⚠️ 重要注意事项（Keycloak 的坑）

• 不是严格的滑动窗口：Keycloak 的 Failure Reset Time 是固定重置，而不是滑动窗口。如果用户在 59 秒时失败了 4 次，第 61 秒失败第 5 次，会触发锁定（但此时重置时间已到，其实会重新计数，具体视版本内部逻辑而定，通常是基于最后一次失败的时间戳来计算重置）。
• 锁定是针对用户的：无论用户在哪个 IP 尝试，只要针对该用户触发了失败次数，该用户账号就会被锁定（Keycloak 的默认暴力破解检测是账号级别的，不是 IP 级别的）。
• 针对分布式攻击的局限：如果攻击者使用大量不同的 IP，每个 IP 只尝试 1 次，Keycloak 的暴力破解机制无法有效防御。此时需要结合外部防火墙或 Minimum Quick Login Wait 来缓解。

推荐设置截图参考：

Enabled: ON
Permanent Lockout: OFF
Max Login Failures: 5
Wait Increment: 30 Minutes
Quick Login Check Milli Seconds: 1000
Minimum Quick Login Wait: 1 Minutes
Max Wait: 30 Minutes
Failure Reset Time: 1 Minutes

修改后点击下方的 Save 即可生效。