keycloak~refresh_token的标准化

内容大纲

1. refresh_token作用
2. 使用方法
3. refresh_token规范
4. keycloak开启refresh_token的限制
5. refresh_token时的错误汇总
6. keycloak中refresh_token的底层逻辑

一 refresh_token作用

refresh_token是用来刷新access_token的，当access_token过期后，可以通过refresh_token来获取新的access_token，而不需要重新登录。

二 使用方法

curl --location --request POST 'https://{keycloak}/auth/realms/{realm}/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={refresh_token}' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}'

三 refresh_token规范

• 每个refresh_token只能使用一次，不可重复使用，KC这边也会进行回收它
• 通过refresh_token获取新的token时，返回值里会带有新的refresh_token，我们应该使用新的refresh_token来覆盖上一次的refresh_token
• refresh_token有效期取决于keycloak~tokens~sso session idle的值，即会话空闲时间，如果refresh_token在这个时间内没有使用，那么它会失效
• refresh_token失效后，当前会话session_state也即失效，此时，需要重新登录

注意：sso session max表示会话最大有效期，在这个时间范围内，用户不需要重新登录，sso session idle表示空间时间，在这个时间内用户不进行操作，也示为退出，用户需要重新登录，这两个值必须大于0；单位为分，小时，天，不支持永久有效期。

四 keycloak开启refresh_token的限制

五 refresh_token时的错误汇总

• 当refresh_token超过限制时，会返回invalid_grant错误，此时，需要重新登录
  

• 再次使用refresh_token，同样返回状态码400，但返回消息体会有变化
  

• 如果当前session已经失效，即会话达到了session max的时间，将返回下面错误
  

• 如果当前客户端与token客户端不一致，将返回下面错误
  

• 如果当前当前端开启了同意许可，将返回下面错误
  

六 keycloak中refresh_token的底层逻辑

1. validateToken方法
   

2. 通过session_state获取userSession对象，如果userSession对象为空，说明refresh_token已经失效，返回400 Session not active
   

3. isSessionValid方法主要验证会话是否有效，主要判断以下几个部分

• 用户会话是否存在,user-session是否存在
• 获取session空闲时间和最大时间，它们的逻辑与是否开启记住我有关
• 会有两层时间的比较，来确定session是否有效
  • 第一层，session空闲时间是否大于（当前时间-最后刷新token时间-容错窗口期（120秒））
  • 第二层，session最大时间是否大于（当前时间-session开始时间）
• 上面两层同时满足，说明session是有效的
  

4. 从userSession中获取当前用户对象
5. 判断用户是否有效
   • 如果用户被删除，返回400 Unknown user
   • 如果用户状态为禁用，返回400 User disabled
   • 如果用户需要一个必要的行为，返回400 User has required action
6. 判断当前refresh_token的建立时间是否早于会话开始时间，正常情况下肯定是晚于会话时间，如果早于，返回400 Refresh toked issued before the user session started
7. 判断当前userSession是否在当前client_id对应的clientSession里，如果没有，返回400 Session doesn't have required client
8. 判断当前refresh_token里的azp是否与请求参数client_id相同，不同返回400 Unmatching clients
9. 验证refresh_token是否被篡改
10. 检查客户端是否有consent的授权许可同意，如果开启了，会返回400 Client no longer has requested consent from user
11. 成功建立新的token对象，整个刷新token流程结束

{
    "access_token": "",
    "expires_in": 120,
    "refresh_expires_in": 300,
    "refresh_token": "",
    "token_type": "Bearer",
    "id_token": "",
    "not-before-policy": 1740449130,
    "session_state": "424b8022-600d-421e-a45d-e0315d1a524d",
    "scope": "openid roles email profile"
}