Keycloak 21自定义注册报错：Expired Code会话超时排查

从你遇到的expired_code错误和跳转提示来看，问题大概率和一次性验证凭证的有效期处理有关，而非普通会话时间逻辑，以下是具体分析和排查方向：

• 核心原因：Keycloak的expired_code错误通常关联注册流程中生成的一次性验证凭证（比如你链接里的hash参数对应的凭证）。这类凭证默认有有效期限制，如果你的自定义代码没正确处理凭证的生成、存储或过期校验，就会触发该错误。

• 排查自定义认证器的关键逻辑：

  1. 检查HashRegistrationAuthenticator中生成注册链接的代码：是否在生成hash或对应凭证时，通过Keycloak的AuthenticationSessionModel或UserModel设置了合理的过期时间？如果没有显式设置，Keycloak会使用全局默认的短有效期，导致链接很快失效。
  2. 查看请求处理逻辑（比如authenticate方法）：是否在验证hash、email参数时，检查了对应凭证的过期状态？如果跳过这一步，Keycloak的底层机制会因为会话中没有有效凭证，判定为expired_code。
  3. 确认会话上下文传递：你的自定义认证器是否在流程中正确维护了AuthenticationSessionModel的状态？比如用户通过链接进入注册流程时，需要刷新或重置会话的过期时间，避免被系统判定为超时。

• 全局配置排查：
  登录Keycloak控制台，进入对应Realm的登录设置页面，查看「用户操作令牌有效期」（User Action Token Lifespan）的配置。如果这个全局值设置得过短（比如默认5分钟），即使自定义代码逻辑正确，也会导致注册链接快速过期。

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