Keycloak登出后调用refresh_token报Session not active如何解决

问题场景 #

基于Keycloak SSO系统实现生物识别授权功能，需要获取用户登出后仍可生效的长生命周期refresh_token，调用携带offline_access scope的token刷新接口时返回Session not active错误，调用命令如下：

curl --location --request POST 'http://localhost:8089/auth/realms/EXTERNAL/protocol/openid-connect/token?prompt=consent&scope=offline_access'
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'prompt: consent'
--header 'scope: offline_access'
--data-urlencode 'client_id=client-credential'
--data-urlencode 'refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI4NGRkZDM1OC1kMDFjLTRjODQtYmE2OC00ODA1MzVlNmM5OWIifQ.eyJleHAiOjE2NTY5MDY5NDQsImlhdCI6MTY1Njg5OTc0NCwianRpIjoiMTkzM2IxNzktOWQxMC00ODI5LTlkY2EtZGRiNGM5ZGM1YzY0IiwiaXNzIjoiaHR0cHM6Ly9kZXYtaWQuc2FmaW4udm4vYXV0aC9yZWFsbXMvRVhURVJOQUwiLCJhdWQiOiJodHRwczovL2Rldi1pZC5zYWZpbi52bi9hdXRoL3JlYWxtcy9FWFRFUk5BTCIsInN1YiI6ImZkMTY3NWVjLWY5YjgtNDRjMS04Yjk5LWJlOTU2M2Y2NTgyMiIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJjbGllbnQtY3JlZGVudGlhbCIsInNlc3Npb25fc3RhdGUiOiI2NDExYzQ2ZC1hMGVmLTRiMDEtOTU0Yi00ZTU4ZTE5Mjc2ZDAiLCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJzaWQiOiI2NDExYzQ2ZC1hMGVmLTRiMDEtOTU0Yi00ZTU4ZTE5Mjc2ZDAifQ.c3ZdvnrG_Y3nuHKIWUGqo-beN-S5MNE-Ywufqym2D54'
--data-urlencode 'grant_type=refresh_token'
--data-urlencode 'scope=offline_access'
--data-urlencode 'client_secret=58f28165-1553-4543-9c66-c2e8c65fexxx'

错误根因 #

• 你当前传入的refresh_token是和用户在线会话强绑定的普通令牌，解码其payload可见scope字段仅为email profile，没有offline_access权限。用户登出后在线会话被Keycloak销毁，绑定该会话的普通refresh_token会直接失效，触发Session not active报错。
• 逻辑错误：offline_access scope必须在用户首次登录授权、第一次换取token的请求中携带申请，后续刷新环节才追加该参数，无法将普通在线refresh_token转换为离线令牌。
• 前置配置缺失：如果Realm或客户端层面没有开启离线访问权限，就算流程正确也无法正常签发离线refresh_token。

修复步骤 #

1. 配置Realm离线会话规则
   登录Keycloak管理控制台，进入EXTERNAL realm，打开Realm Settings -> Tokens配置页，根据生物识别场景的长周期需求设置Offline Session Max（离线会话最大有效期）、Offline Session Idle（离线会话空闲超时时间），避免过期时间过短不符合业务要求。
2. 给客户端开通离线访问权限
   进入Clients菜单，选中client-credential客户端：
   • 在Settings页按需开启Consent Required（如果需要用户显式同意离线访问权限）
   • 切换到Scope页，确认offline_access在允许的scope列表中，没有被加入禁用范围；如果客户端使用服务账号模式，还要给服务账号绑定offline_access对应的角色权限。
3. 调整令牌申请逻辑，首次授权就携带offline_access
   废弃当前使用的普通refresh_token，在用户下次走登录授权流程（授权码、密码等首次换token的接口）时，就带上scope=offline_access参数，Keycloak此时会生成绑定独立离线会话的offline refresh_token，这类令牌不与用户在线登录会话绑定，用户登出在线系统后，离线refresh_token依然可以正常刷新获取access_token，满足生物识别免登的长周期授权需求。
4. 简化刷新请求参数
   你当前的curl请求在URL参数、请求头、请求体中重复传递了scope、prompt参数，冗余参数可能导致Keycloak解析异常，刷新时直接把参数放到form表单请求体中即可，参考示例：

   curl --location --request POST 'http://localhost:8089/auth/realms/EXTERNAL/protocol/openid-connect/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'client_id=client-credential' \
   --data-urlencode 'client_secret=58f28165-1553-4543-9c66-c2e8c65fexxx' \
   --data-urlencode 'grant_type=refresh_token' \
   --data-urlencode 'refresh_token=<首次授权获取到的offline类型refresh_token>' \
   --data-urlencode 'scope=offline_access'
   

校验小技巧：拿到新的refresh_token后可以直接解码payload，如果scope字段包含offline_access，才是真正的长生命周期离线令牌。

内容的提问来源于stack exchange，提问作者Quân Đoàn