如何在Keycloak中实现自定义暴力破解检测扩展？

Keycloak原生支持自定义暴力破解检测逻辑，无需修改平台核心源码，通过官方SPI扩展机制即可替换内置的默认检测规则，完全可以实现你需要的阶梯式锁定需求。

内置默认逻辑的局限 #

Keycloak默认启用的暴力破解保护器为DefaultBruteForceProtector，其锁定时长计算逻辑为硬编码实现，采用公式 wait time * (countOfFailures / maxFailures) 计算锁定时长，其中除法为整数向下取整运算，确实不支持配置「首次累计X次失败锁X分钟、解锁后再次失败触发独立Y时长锁定」的分阶段阶梯规则，你提到的“配置最大锁定时长10分钟时，前5次失败锁10分钟、第6次失败锁20分钟”就是该固定计算逻辑导致的，无法通过后台配置调整。

自定义实现步骤 #

你可以通过扩展BruteForceProtector SPI替换默认实现，核心操作如下：

• 新建自定义扩展模块，引入Keycloak核心依赖，直接继承DefaultBruteForceProtector类，重写锁定判定、时长计算相关方法：
  • 重写isTemporarilyDisabled方法，自定义失败计数规则：可以复用Keycloak默认存储在用户属性中的失败次数、最后失败时间、历史锁定记录字段，单独区分首次触发锁定、解锁后二次触发锁定两个阶段，分别匹配你需要的X、Y锁定时长规则
  • 自定义配置参数可通过Keycloak的配置SPI注册到Realm设置页，支持在后台可视化配置首次失败阈值、首次锁定时长、二次锁定时长等参数，无需硬编码
• 在扩展jar包的META-INF/services/目录下添加SPI注册文件，声明你的自定义BruteForceProtector实现，设置优先级高于默认实现
• 部署扩展jar到Keycloak的providers目录，执行构建命令重启后即可生效，原有内置的暴力破解检测开关、IP白名单等能力可以直接复用，不需要重复实现。

实现注意：自定义逻辑不需要修改原有失败计数的存储结构，Keycloak默认会持久化用户的登录失败记录，你只需要调整阈值判定和时长计算的分支逻辑即可，整体扩展成本很低，没有框架层面的限制。

内容的提问来源于stack exchange，提问作者Djordje