Keycloak用户迁移插件未调用REST API端点问题排查

一、先确认插件是否成功部署加载 #

如果插件未被Keycloak识别，后续配置都不会生效：

• 查看Keycloak Pod日志：在K8s中执行kubectl logs <keycloak-pod-name>，搜索是否有Deploying user storage provider: user-migration类的加载日志，或Jar包缺失、版本不兼容的报错。
• 检查Admin Console的用户存储列表：进入User Federation页面，确认能看到User Migration选项，否则说明插件未部署成功。
• 验证插件Jar存在性：进入Keycloak Pod，执行ls /opt/keycloak/providers，确认包含用户迁移插件的Jar文件。

二、检查用户联合实例的核心配置 #

插件的触发逻辑依赖正确的用户联合配置：

• 确认优先级设置：Keycloak用户存储的优先级数字越低，被查询的顺序越靠前。若要在本地用户找不到时才触发插件，需将插件实例的Priority设为比本地存储（默认通常为0）更大的数值（比如10），确保本地存储先被检查。
• 核对REST端点配置：确认填写的端点URL无拼写错误（注意HTTP/HTTPS、末尾斜杠），且Enabled开关处于开启状态。
• 匹配用户查找字段：检查插件的Lookup Attribute设置（是username还是email），确保登录时输入的凭证与该字段匹配——比如设为email时，需用邮箱而非用户名登录才会触发插件调用。

三、调整日志级别获取插件调试信息 #

当前Debug日志未包含插件内容，需单独开启插件包的DEBUG日志：

• 在Keycloak启动参数中添加：--log-level=com.github.danielfrak.keycloak.userstorage=DEBUG（K8s环境可修改Deployment的command参数）。
• 重新查看Pod日志，此时应能看到插件初始化、用户查找时的详细日志（如Looking up user with username: xxx、Calling migration endpoint: xxx），以此判断插件是否被触发。

四、验证触发条件与网络连通性 #

• 确认用户不存在于Keycloak本地：在Admin Console的Users页面搜索登录用的用户名/邮箱，确保无匹配结果。
• 测试Pod内部网络：进入Keycloak Pod执行curl <你的REST端点URL>，确认能正常返回用户数据——浏览器/Postman能访问不代表Pod内部可访问，需排查K8s NetworkPolicy、Service是否限制了流量。

五、关于认证流与OAuth客户端的说明 #

该插件作为用户存储提供商工作，无需额外修改认证流或OAuth客户端配置。默认登录流程会自动触发用户存储的查找逻辑，问题不在这两类配置上。

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