Keycloak Access Token未到有效期提前失效问题排查与解决

问题背景 #

配置Realm的Access Token Lifespan为5分钟，但实际Access Token在约4分15秒时就失效，调用后端API返回如下错误：

WWW-Authenticate: Bearer error="invalid_token", error_description="An error occurred while attempting to decode the Jwt: Jwt expired at 2023-06-01T13:09:09Z", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"

常见原因及解决方法 #

1. 多服务器时钟不同步 #

这是最常见的原因：JWT的过期时间（exp字段）基于Keycloak服务器的系统时间生成，但如果客户端应用服务器或后端API服务器的时钟比Keycloak服务器快，就会提前判定Token已过期。比如Keycloak生成的Token过期时间是13:09，后端服务器时钟是13:08:15，此时后端会认为Token已经过期，返回错误。

解决：

• 确保Keycloak服务器、客户端服务器、后端API服务器的系统时间完全同步，建议使用NTP服务（如Linux的chronyd、Windows的系统时间同步功能）统一校准时间。
• 手动验证：解码Access Token（用JWT解码工具查看exp和iat字段），对比Keycloak服务器时间与后端服务器时间，确认是否存在时钟差。

2. 客户端级别的Token配置覆盖了Realm设置 #

Keycloak允许客户端单独配置Token有效期，该配置优先级高于Realm全局设置。如果你的客户端在Token Settings里单独设置了Access Token Lifespan，会覆盖Realm的5分钟配置。

解决：

• 登录Keycloak控制台，进入对应客户端的Settings -> Advanced（或Token Settings），检查是否有自定义的Access Token Lifespan配置，若有则修改为5分钟或删除该配置（继承Realm设置）。

3. 后端JWT验证的时钟偏移配置不足 #

部分JWT验证库默认会设置一个时钟偏移容忍值（比如30秒），用于处理微小的时钟差，但如果你的后端没有配置或配置的容忍值过小，也可能导致提前判定过期。

解决：

• 在后端的JWT验证逻辑中调整时钟偏移容忍值。例如：
  • Spring Security：配置jwt.setClockSkew(Duration.ofSeconds(60))，允许最多60秒的时钟偏差。
  • 其他语言/框架：查找对应JWT库的clockSkew或类似配置项，设置合理的容忍时间。

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