Keycloak禁用重复邮箱后注册仍触发内部服务器错误 如何实现邮箱唯一性校验？

问题表现 #

• 指定realm下的公共注册流程中，系统未在入参校验阶段触发邮箱唯一性前置检查，直接返回内部服务器500错误
• 应用日志中可见数据库层硬约束报错：

Caused by: com.microsoft.sqlserver.jdbc.SQLServerException: Violation of UNIQUE KEY constraint 'UK_DYKN684SL8UP1CRFEI6ECKHD7'. Cannot insert duplicate key in object 'dbo.USER_ENTITY'. The duplicate key value is (my_realm, user@email.com).

• 前置排查已确认：对应域的配置中已关闭允许重复邮箱的开关，但校验逻辑未生效，报错直接穿透到数据库层抛出

问题根因 #

• Keycloak 原生的邮箱唯一性校验逻辑存在场景覆盖缺口：公共注册分支下，应用层未主动触发同域邮箱重复查询，所有唯一性判断完全下推到数据库的唯一约束完成
• 该实现和用户名的校验逻辑不一致：用户名校验会在入参阶段提前查询库内是否存在同域重复值，命中就直接返回参数错误，不会走到数据库插入步骤

落地修复步骤 #

• 校验域配置项匹配性
  • 进入对应realm的Realm Settings > Login配置页，确认两个核心开关状态：
    • 关闭Duplicate emails选项，即启用同域邮箱不可重复的规则
    • 若开启Email as username选项，需同步确认该模式下用户名唯一性校验和邮箱规则的绑定关系，避免规则冲突导致校验失效
• 对齐校验触发逻辑
  • 参考用户名校验的实现链路，在公共注册流程的参数校验阶段增加前置查询：
    • 通过UserProvider接口查询当前realm下，是否存在和注册入参邮箱值完全一致的已注册用户
    • 若查询命中重复值，直接返回Keycloak标准的参数校验错误（对应"邮箱已被注册"的提示），阻断后续数据库插入流程
• 增加异常兜底转换
  • 在接口层增加数据库约束异常的捕获分支：
    • 当捕获到UK_DYKN684SL8UP1CRFEI6ECKHD7约束触发的异常时，不将原始数据库报错返回给前端，统一转换为面向用户的友好提示，避免暴露内部系统细节

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