如何在Keycloak 18.0.0的认证响应中启用session_state参数

针对Keycloak 18.0.0中session_state参数从令牌响应中消失、且兼容模式配置无效的问题，可以尝试以下几种解决方式：

• 确认配置并刷新缓存
  先确保你已经在对应客户端的Clients -> [目标客户端] -> OpenID Connect Compatibility Modes里勾选了Include Session State in Token Response选项。修改完成后，必须重启Keycloak服务，或者执行缓存清理命令：

  # 适用于Quarkus版本的Keycloak
  bin/kc.sh clear-cache
  

  很多时候配置不生效是因为缓存没有刷新。

• 检查认证请求的scope参数
  session_state是OpenID Connect规范的参数，只有当认证请求中包含scope=openid时才会返回。请确认你的授权请求和令牌请求都正确携带了这个scope参数，缺少的话即便开启配置也不会返回该字段。

• 通过SPI扩展强制注入session_state
  如果上述方法都无效，可以编写一个简单的Token增强器SPI，手动将session_state添加到令牌响应中：

  1. 实现TokenEnhancer接口，从当前认证会话中获取sessionId并添加到令牌的额外声明中：

  import org.keycloak.models.AuthenticationSessionModel;
  import org.keycloak.protocol.oidc.TokenEnhancer;
  import org.keycloak.protocol.oidc.TokenEnhancerContext;
  import org.keycloak.representations.AccessToken;
  
  public class SessionStateTokenEnhancer implements TokenEnhancer {
      @Override
      public AccessToken enhance(AccessToken accessToken, TokenEnhancerContext context) {
          AuthenticationSessionModel authSession = context.getAuthenticationSession();
          if (authSession != null) {
              accessToken.getOtherClaims().put("session_state", authSession.getSessionId());
          }
          return accessToken;
      }
  }
  

  2. 将代码打包成jar，放到Keycloak的providers目录下，然后执行构建命令并重启服务：

  bin/kc.sh build
  bin/kc.sh start
  

• 启动时强制开启兼容参数
  可以通过启动参数强制开启session_state的返回，避免UI配置失效的问题：

  • 本地部署：

    bin/kc.sh start --spi-oidc-include-session-state-in-token-response=true
    

  • Docker部署：

    docker run -d \
      -p 8080:8080 \
      -e KC_SPI_OIDC_INCLUDE_SESSION_STATE_IN_TOKEN_RESPONSE=true \
      quay.io/keycloak/keycloak:18.0.0 start-dev
    

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