Keycloak离线会话清理机制的问题分析与解决方案

问题背景

在Keycloak身份认证与授权系统中，离线会话(offline session)机制允许客户端在用户不活跃的情况下继续使用刷新令牌(refresh token)获取新的访问令牌。这一功能对于需要长期保持用户登录状态的应用程序尤为重要。

问题现象

当系统配置了clientOfflineSessionIdleTimeout参数(值大于0)且同时将offlineSessionMaxLifespanEnabled设置为false时，会出现一个矛盾现象：

1. 按照预期，当offlineSessionMaxLifespanEnabled为false时，刷新令牌应该永不过期
2. 但实际上，Keycloak内部每15分钟运行一次的定时任务会根据clientOfflineSessionIdleTimeout的值清理"过期"的离线会话
3. 这导致即使配置了永不过期的刷新令牌，也会被系统错误地清理掉

技术原理分析

Keycloak的离线会话管理涉及两个关键参数：

1. clientOfflineSessionIdleTimeout：定义客户端离线会话的空闲超时时间(秒)
2. offlineSessionMaxLifespanEnabled：布尔值，控制是否启用离线会话的最大生命周期

系统内部有一个名为ClearExpiredUserSessions的定时任务，默认每15分钟执行一次，负责清理过期的用户会话。该任务在判断离线会话是否过期时，仅考虑了clientOfflineSessionIdleTimeout参数，而忽略了offlineSessionMaxLifespanEnabled的设置。

影响范围

该问题影响以下版本：

• 26.0.5
• 26.1.4
• 以及最新的nightly build版本

受影响的功能主要是使用离线令牌的客户端应用，特别是那些需要长期保持会话的应用场景。

解决方案建议

从技术实现角度，建议修改ClearExpiredUserSessions任务的逻辑，使其在清理离线会话时同时考虑两个参数的设置：

1. 当offlineSessionMaxLifespanEnabled为false时，不应基于clientOfflineSessionIdleTimeout清理会话
2. 只有当offlineSessionMaxLifespanEnabled为true时，才需要考虑超时设置

临时规避措施

在官方修复发布前，可以采取以下临时方案：

1. 避免同时设置clientOfflineSessionIdleTimeout和禁用offlineSessionMaxLifespanEnabled
2. 如果需要长期有效的刷新令牌，建议仅设置offlineSessionMaxLifespanEnabled为false

总结

Keycloak的离线会话清理机制存在逻辑缺陷，导致会话生命周期配置不一致。该问题已在多个版本中确认存在，需要修改核心清理逻辑以确保配置参数的一致性。对于依赖长期有效刷新令牌的应用，建议关注该问题的修复进展或采用临时规避方案。