Keycloak 18 LDAP组映射器批量导入组后用户认证失败问题

问题场景 #

应用已集成Keycloak 18，包含1个自定义Realm和约150个Realm角色，已配置LDAP并导入部分LDAP组的用户，此前手动维护角色映射。为实现自动化，使用LDAP组映射器，因150个组无法全部塞进过滤器，改用通配符模式后成功导入所有组，但LDAP用户认证失败，报错如下：

2024-01-29 01:55:10,188 ERROR [org.keycloak.services.error.KeycloakErrorHandler] (executor-thread-7) Uncaught server error: com.fasterxml.jackson.databind.JsonMappingException: [no message for java.lang.NullPointerException]

Caused by: java.lang.NullPointerException
        at org.keycloak.models.cache.infinispan.UserCacheSession.getUserByUsername(UserCacheSession.java:243)

测试验证：导入3个组时认证正常，通配符能正确识别组名，但全量导入150个组后必现认证失败。

问题分析 #

这个空指针异常出现在用户缓存会话逻辑中，核心原因是通配符一次性导入的组数量过多，触发了Keycloak 18缓存机制的处理bug——大量组映射关联到用户后，缓存加载用户数据时出现空引用。此外，也可能是组属性映射存在空值，导致缓存序列化失败。

解决步骤 #

1. 临时禁用用户缓存验证问题根源 #

进入Keycloak管理控制台 → 目标Realm → 左侧菜单「缓存」→ 找到「用户缓存」并禁用，重启Keycloak后测试认证。如果认证恢复正常，直接坐实是缓存机制的问题。

2. 拆分LDAP组映射器，避免单映射器处理过量组 #

放弃单个通配符映射所有组，拆分多个LDAP组映射器：

• 按组名前缀分组，比如创建5个映射器，每个负责30个组（过滤器写cn=RoleGroup1-*、cn=RoleGroup2-*等）
• 每个映射器保持相同的属性映射规则（LDAP组cn对应Realm角色名、自动创建角色等）

3. 检查LDAP组属性映射的正确性 #

对照组映射器配置，确认以下字段和LDAP实际属性完全匹配：

• LDAP组DN的基础路径是否正确
• 组名LDAP属性（比如cn）是否确实存储了对应的角色名称
• 确保所有导入的LDAP组都有非空的角色名称属性，避免空值进入缓存导致序列化异常

4. 升级Keycloak到稳定版本 #

Keycloak 18属于旧版本，后续20+版本已修复不少缓存相关的空指针问题。先在测试环境验证应用兼容性，再升级生产环境版本。

5. 调整Infinispan缓存参数（进阶） #

如果必须保留Keycloak 18，可调整Infinispan缓存配置：

• 找到standalone.xml或domain.xml中的用户缓存配置段
• 增大缓存条目上限（max-entries）、调整缓存超时时间（expiration）
• 清理现有缓存后重启服务测试

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