修改缓存策略时Keycloak User Storage SPI出现功能异常问题

可能的核心原因 #

• 非默认缓存策略（如每日清除）会改变Keycloak对用户存储Provider的缓存生命周期管理，若自定义Provider未实现CacheableUserStorageProvider接口，会导致查询逻辑被缓存拦截，无法触发远程API调用
• 缓存策略修改后，残留的旧缓存数据未被清理，即使改回默认策略，旧缓存仍会干扰Provider的正常运行
• 自定义Provider的查询逻辑未与Keycloak缓存机制兼容，导致缓存生效后无法正确从远程系统拉取用户数据

可行解决方案 #

1. 确保实现CacheableUserStorageProvider接口 #

该接口是Keycloak识别缓存策略的核心，未实现会导致非默认缓存策略失效：

@Override
public CachePolicy getCachePolicy() {
    // 直接返回配置中设置的缓存策略
    return CachePolicy.valueOf(this.config.getCachePolicy());
}

2. 添加缓存清理逻辑 #

在Provider的close()方法中手动清理用户缓存，避免残留数据干扰：

@Override
public void close() {
    UserCache userCache = session.userCache();
    if (userCache != null) {
        userCache.invalidate(this.realm);
    }
}

3. 修改缓存策略后强制刷新缓存 #

无需删除重装Provider，直接通过以下方式清理缓存：

• 管理控制台：进入对应Realm → 左侧菜单Cache → 选择User Cache → 点击Clear按钮
• Admin API：发送POST请求到/admin/realms/{realm}/clear-cache，指定清理user类型缓存

4. 兼容缓存逻辑调整查询方法 #

实现UserQueryProvider时，需明确缓存检查与远程API调用的顺序，确保缓存缺失时能拉取远程数据并更新缓存：

@Override
public UserModel getUserByUsername(String username, RealmModel realm) {
    // 先检查缓存
    UserModel cachedUser = session.userCache().getUserByUsername(username, realm);
    if (cachedUser != null) {
        return cachedUser;
    }
    // 缓存缺失时调用远程API
    RemoteUser remoteUser = remoteApiClient.getUser(username);
    if (remoteUser == null) {
        return null;
    }
    // 转换为Keycloak UserModel并存入缓存
    UserModel user = createUserModel(remoteUser, realm);
    session.userCache().addUser(realm, user);
    return user;
}

注意事项 #

• Keycloak 21.0.1对自定义SPI的缓存兼容性要求严格，需严格遵循官方SPI规范实现缓存相关接口
• 修改缓存策略后必须清理对应Realm的用户缓存，否则旧缓存会持续覆盖新查询结果
• 可在Provider启动时打印缓存策略配置，确认配置是否正确加载

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