如何使用grant_type=refresh_token从Keycloak获取Offline Access令牌

核心问题根源 #

OIDC协议和Keycloak的实现均不支持在refresh_token授权流程中新增原始授权未授予的scope。你当前在刷新请求时才追加offline_access参数的操作是无效的，所以返回的scope始终只有首次授权时拿到的openid。

正确操作步骤 #

• 第一步：首次请求令牌时必须携带offline_access scope
  不管你使用授权码流、隐式流还是其他支持的OIDC认证流程，第一次向Keycloak申请令牌时，就要在scope参数中加入offline_access，示例授权码流的发起请求如下：

  https://<domain>/auth/realms/public/protocol/openid-connect/auth?client_id=<id>&response_type=code&scope=openid offline_access&redirect_uri=<你的应用回调地址>
  

  你之前使用grant_type=password能成功拿到离线令牌，就是因为你在首次密码模式请求时就已经携带了该scope。

• 第二步：确认Keycloak侧配置无误

  1. 进入对应客户端的「Scope」配置页，确认offline_access已经被加入到客户端的可选scope列表或默认scope列表
  2. 进入对应Realm的「Roles」-「Default Roles」配置页，确认offline_access角色已经被设置为Realm默认角色，或者你的目标用户已经被单独分配了该角色
  3. 如果客户端开启了scope限制，确保没有屏蔽offline_access scope的使用

• 第三步：刷新令牌时无需额外调整参数
  首次授权拿到包含offline_access的refresh_token之后，后续刷新令牌的请求不需要特意携带scope参数，Keycloak会自动继承原始授权的scope，返回的新令牌会包含offline_access，同时管理控制台的Offline Tokens计数会正常更新。

现有问题修复方式 #

你当前持有的refresh_token是首次授权未申请offline_access时下发的，无法通过刷新操作补加scope。你需要引导用户重新走一次完整的授权流程，首次请求就携带offline_access scope，拿到新的refresh_token之后再进行刷新操作即可符合预期。

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