Keycloak中自定义用户存储提供商无法注册的问题排查

1. 执行Keycloak构建命令（Quarkus模式必需） #

Keycloak 21+基于Quarkus，新增的提供商需要通过构建步骤让Keycloak发现并注册。你仅复制JAR但未执行构建：

# 进入容器
docker exec -it keycloak /bin/bash
# 执行构建命令
/opt/keycloak/bin/kc.sh build
# 退出并重启容器
exit
docker restart keycloak

完成后查看日志，应该会出现类似Registered provider: custom-user-storage-provider的注册信息。

2. 在Keycloak管理控制台启用自定义提供商 #

即使JAR被正确注册，你还需要在目标Realm中添加并配置该用户存储提供商：

• 登录Keycloak Admin UI
• 进入目标Realm → User Federation
• 点击Add provider，选择你的custom-user-storage-provider
• 保存配置（当前实现无需额外参数）

3. 检查Maven依赖范围 #

确保pom.xml中Keycloak相关依赖使用provided范围，避免打包重复类导致冲突：

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-core</artifactId>
    <version>26.1.3</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-server-spi</artifactId>
    <version>26.1.3</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-server-spi-private</artifactId>
    <version>26.1.3</version>
    <scope>provided</scope>
</dependency>

重新打包JAR并替换容器中的文件，再执行构建和重启。

4. 验证服务文件正确性 #

确认META-INF/services/org.keycloak.storage.UserStorageProviderFactory文件内容完全匹配工厂类的全限定名：

com.my_app.user_provider.CustomUserStorageProviderFactory

注意：文件路径、名称需完全一致，大小写敏感，且文件内无多余空格或换行。

5. 修正代码逻辑问题 #

当前getUserByUsername方法存在逻辑缺陷：你从默认用户存储中获取用户，仅当用户已存在于Keycloak内置存储时才会触发你的代码。测试阶段可修改为：

@Override
public UserModel getUserByUsername(final RealmModel realmModel, final String username) {
    // 尝试获取用户，不存在则创建临时用户
    UserModel user = session.users().getUserByUsername(realmModel, username);
    if (user == null) {
        user = session.users().addUser(realmModel, username);
        user.setEmail("test-email@gmail.com");
        user.setEnabled(true);
    } else {
        user.setEmail("test-email@gmail.com");
    }
    return user;
}

6. 开启调试日志定位问题 #

如果以上步骤无效，开启调试日志查看注册细节：

# 重启容器时设置日志级别
docker run -e KEYCLOAK_LOG_LEVEL=DEBUG [其他原有参数]

重启后搜索日志中custom-user-storage-provider或UserStorageProviderFactory相关条目，定位注册失败原因。

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