Keycloak v21.0.2用户缓存配置咨询：禁用或分布式同步设置

背景 #

我们需要将旧平台的密码及用户属性同步至Keycloak，该功能通过Keycloak API更新用户信息实现。但发现用户更新密码后有时无法立即登录，排查同步流程无问题，怀疑是默认缓存配置不符需求。尝试将users缓存改为分布式配置（如下代码）时遇到序列化错误，且不确定users缓存能否变更为非local类型：

<distributed-cache name="users" owners="2">
    <encoding>
        <key media-type="application/x-java-object"/>
        <value media-type="application/x-java-object"/>
    </encoding>
    <expiration max-idle="-1" lifespan="-1" interval="300000"/>
    <memory max-count="-1"/>
</distributed-cache>

问题1：是否可以禁用users缓存？若可以，如何操作？ #

可以禁用users缓存，你找到的配置方向是正确的，具体操作步骤如下：

1. 打开Keycloak的核心配置文件：单机模式用standalone.xml，域模式用domain.xml
2. 定位到infinispan子系统下的cache-container name="keycloak"节点
3. 替换原有的users缓存配置为：

<local-cache name="users" start="NONE">
</local-cache>

start="NONE"会让Keycloak启动时不初始化该缓存，所有用户查询直接走数据库，彻底避免缓存延迟问题。但需注意，禁用缓存会增加数据库查询压力，需结合系统负载评估可行性。

问题2：如何正确配置users为分布式缓存，确保用户信息变更时跨实例即时同步？ #

要解决序列化错误并实现分布式缓存的跨实例同步，需使用Keycloak内置的用户缓存序列化器，正确配置如下：

<distributed-cache name="users" owners="2">
    <encoding>
        <key media-type="application/x-java-object"/>
        <value media-type="application/x-java-object">
            <serializer>
                <class>org.keycloak.models.cache.infinispan.UserCacheEntryExternalizer</class>
            </serializer>
        </value>
    </encoding>
    <expiration max-idle="-1" lifespan="-1" interval="300000"/>
    <memory max-count="-1"/>
    <transaction mode="NON_XA"/>
</distributed-cache>

关键配置说明：

• 指定UserCacheEntryExternalizer作为序列化器：这是Keycloak专门为用户缓存条目提供的序列化实现，能解决自定义分布式配置时的序列化错误。
• owners="2"：设置每个缓存条目在集群中2个节点备份，可根据集群规模调整数值，平衡可用性与资源占用。
• 集群通信配置：确保所有Keycloak实例的Infinispan集群通信正常（如TCP栈、JDBC ping等配置正确），否则缓存同步会失效。
• 自动缓存失效：用户信息通过API更新后，Keycloak会自动触发缓存条目失效，集群内所有节点会自动拉取最新数据，实现即时同步。

补充注意：修改配置后需重启所有Keycloak实例，确保配置生效。

内容的提问来源于stack exchange，提问作者Michał P.