Keycloak用户存储提供者在用户联合中不可见的原因排查求助

• Jar包本身存在问题

  • 检查Jar包是否正确实现UserStorageProviderFactory接口，且在META-INF/services/org.keycloak.storage.UserStorageProviderFactory文件中，正确写入了该工厂类的全限定名。若注册文件缺失或类名/路径错误，Keycloak无法扫描到扩展。
  • 确认Jar编译依赖的Keycloak版本与运行版本完全一致，版本不兼容会导致SPI无法正常加载。

• 部署与构建流程有误

  • 核实Jar文件确实已复制到Keycloak的providers目录，且Keycloak进程拥有该文件的读取权限，可通过ls -l providers/命令查看文件状态。
  • 查看kc.sh build的构建日志，搜索django-user-storage或你的提供者类名，确认构建过程是否扫描到该Jar。若构建阶段未识别，启动后自然不会显示扩展。
  • 若使用容器部署，需确认providers目录已正确挂载到容器内，且构建步骤是在容器环境中执行的，挂载路径错误会导致Jar无法被识别。

• Keycloak配置或权限不足

  • 检查当前登录的Keycloak用户是否拥有Realm管理员权限，只有具备该权限的用户才能在用户联合中看到扩展选项，权限不足的用户无法查看。
  • 确认Keycloak启动配置未禁用SPI扫描，比如kc.sh start是否添加了限制SPI加载的参数，或keycloak.conf中是否存在相关禁用配置。

• 日志细节未被挖掘

  • 即使表面日志无报错，可将日志级别调整为DEBUG后重启Keycloak，执行kc.sh start --log-level=DEBUG，搜索UserStorageProvider相关日志，查看是否存在类找不到、依赖缺失等加载失败的细节。

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