Keycloak中用户操作无法刷新SSO会话闲置时长问题排查

核心原因分析 #

Keycloak的SSO会话闲置超时是基于User Session的lastSessionRefresh字段更新逻辑判断的，单纯刷新Access Token不一定会触发该字段更新——只有刷新请求满足特定条件时，Keycloak才会重置闲置计时。

具体排查点与修复方案 #

• 确认Refresh Token请求的scope参数是否正确
  默认情况下，仅携带openid scope的刷新请求不会更新User Session的闲置时间。需要在刷新请求中添加offline_access，确保参数包含能触发会话刷新的范围。PHP示例代码：

$params = [
    'grant_type' => 'refresh_token',
    'client_id' => '你的客户端ID',
    'refresh_token' => $存储的旧刷新令牌,
    'scope' => 'openid offline_access',
    'client_secret' => '你的客户端密钥'
];

• 检查客户端的Refresh Token Max Idle配置
  进入Keycloak后台对应Realm的客户端设置，在Advanced Settings中查看Refresh Token Max Idle值。如果该值小于SSO会话闲置时长（比如设成了5分钟），会导致刷新令牌先过期，无法持续触发会话更新，最终SSO会话超时。建议将此值设为大于等于SSO会话闲置时长（如15分钟）。

• 验证User Session的Last Session Refresh是否更新
  在Keycloak后台进入对应Realm > 用户 > 目标用户 > Sessions，观察每次刷新令牌后，会话的Last Session Refresh时间是否同步更新。如果没有更新，说明刷新请求未触发会话刷新逻辑，需调整请求参数或客户端配置。

• 确认PHP应用是否替换了新的Refresh Token
  Keycloak默认采用滚动刷新策略，每次刷新会返回新的刷新令牌。如果应用没有将新令牌替换旧的存储值（比如存在Session或数据库中），后续刷新会使用过期令牌，无法触发会话更新，最终导致SSO会话超时。

额外注意事项 #

Keycloak的SSO会话闲置超时是从最后一次触发会话刷新的动作开始计算，这里的动作包括用户主动访问应用页面（触发认证校验）或携带正确参数的刷新令牌请求。如果应用仅靠后台自动刷新，务必确保请求参数能正确触发会话刷新。

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