如何配置Keycloak 21.0.1使用Redis作为会话存储

问题根源 #

Keycloak 21.x基于Quarkus重构，彻底抛弃了旧版本（WildFly时代）的XML SPI配置方式，你之前使用的XML配置文件在新版本中不会被读取，这是配置失效的核心原因。

正确配置步骤 #

1. 安装Redis扩展 #

Keycloak 21.x需显式启用Redis扩展，执行构建命令（替换KEYCLOAK_HOME为你的安装目录，--db=postgres替换为实际使用的数据库类型）：

${KEYCLOAK_HOME}/bin/kc.sh build --db=postgres --features=redis

2. 配置Redis会话存储 #

新版本采用conf/keycloak.conf配置文件或启动参数进行配置，以下两种方式二选一：

方式一：修改conf/keycloak.conf

在配置文件中添加Redis相关配置：

# 指定会话存储为Redis
spi-session-store-provider=redis

# Redis基础连接配置
spi-session-store-redis-host=localhost
spi-session-store-redis-port=6379
spi-session-store-redis-database=0
spi-session-store-redis-password=xxxx
spi-session-store-redis-timeout=5000
spi-session-store-redis-key-prefix=keycloak-session:

# 连接池配置
spi-session-store-redis-pool-size=20
spi-session-store-redis-single-pool=true

方式二：启动时传入参数

直接通过启动命令指定Redis配置：

${KEYCLOAK_HOME}/bin/kc.sh start \
  --spi-session-store-provider=redis \
  --spi-session-store-redis-host=localhost \
  --spi-session-store-redis-port=6379 \
  --spi-session-store-redis-database=0 \
  --spi-session-store-redis-password=xxxx \
  --spi-session-store-redis-timeout=5000 \
  --spi-session-store-redis-key-prefix=keycloak-session: \
  --spi-session-store-redis-pool-size=20 \
  --spi-session-store-redis-single-pool=true

3. 与Spring Session共享会话的关键配置 #

要实现跨服务会话共享，必须保证Keycloak与Spring Boot应用的以下配置一致：

• Key前缀：将Keycloak的spi-session-store-redis-key-prefix改为Spring Session默认的spring:session:，或在Spring Boot中配置spring.session.redis.namespace=keycloak-session:对齐前缀
• 序列化方式：Keycloak默认使用Jackson序列化，Spring Session需配置相同的序列化器：

  @Configuration
  @EnableRedisHttpSession
  public class RedisSessionConfig {
      @Bean
      public RedisSerializer<Object> springSessionDefaultRedisSerializer() {
          return new GenericJackson2JsonRedisSerializer();
      }
  }
  

• Redis数据库：两者必须使用同一个数据库（如都配置为0）
• 会话超时：Keycloak的spi-session-store-redis-timeout需与Spring Boot的server.servlet.session.timeout保持一致

4. 验证配置有效性 #

启动Keycloak后，查看日志中是否出现以下内容，确认Redis会话存储加载成功：

INFO  [org.keycloak.quarkus.runtime.storage.legacy.redis.RedisSessionStoreProviderFactory] (main) Redis session store provider initialized

同时可通过Redis客户端查看是否生成对应前缀的会话键。

常见排查点 #

• 若提示Redis扩展未找到，检查构建命令是否添加--features=redis参数并执行成功
• 若会话未写入Redis，验证Redis连接参数（主机、端口、密码）的正确性，确保Keycloak服务器能访问Redis实例
• 若共享会话失败，逐一核对两端的键前缀、序列化方式、Redis数据库配置是否完全匹配

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