Keycloak User SPI迁移导入问题：凭证导入失败求助

问题背景 #

从旧数据库迁移，已实现自定义User Storage SPI用于验证旧系统凭证，基础验证功能正常。需求为：旧系统登录验证通过时，在Keycloak创建匹配的本地用户账户并绑定密码凭证。

预期流程 #

登录 ->
        -> 触发自定义User Storage SPI
        -> 验证成功
            -> 若本地用户不存在则创建
            -> 绑定新密码凭证
        -> 登录成功
    登出
    再次登录 ->
        -> 检查Keycloak本地用户（不再触发User Storage SPI）
        -> 账号密码校验
        -> 登录成功

实际问题 #

二次登录始终失败，且不再触发User Storage SPI。已确认本地用户及凭证已在realm、public.user_entity和public.credential表中创建，但登录时控制台报错：

DEBUG [org.keycloak.credential.PasswordCredentialProvider] (executor-thread-1) Failed password validation for user [redacted]

提供的isValid函数代码 #

@Override
public boolean isValid(RealmModel realm, UserModel user, CredentialInput input) {
    UserCredentialModel cred = (UserCredentialModel)input;
    String password = cred.getValue();

    // 验证旧系统凭证
    String loginOutput = loginCMD(user.getUsername(), password, xForwardedFor);

    // 旧系统验证失败返回"false"
    Boolean valid = !loginOutput.equals("false");

    if (!valid) {
        return valid;
    }

    // 检查本地用户是否存在
    UserModel local = UserStoragePrivateUtil.userLocalStorage(session).getUserByUsername(realm, user.getUsername());

    if (local != null) {
        return valid;
    }

    // 创建本地用户
    local = UserStoragePrivateUtil.userLocalStorage(session).addUser(realm, user.getUsername());
    local.setFirstName("firstName");
    local.setLastName("lastName");
    local.setEmail(user.getUsername());
    local.setEnabled(true);
    local.setUsername(user.getUsername());

    // 手动实例化密码加密提供者
    Pbkdf2PasswordHashProvider encoder = new Pbkdf2PasswordHashProvider(
        Pbkdf2Sha512PasswordHashProviderFactory.ID,
        Pbkdf2Sha512PasswordHashProviderFactory.PBKDF2_ALGORITHM,
        Pbkdf2Sha512PasswordHashProviderFactory.DEFAULT_ITERATIONS,
        256 // 尝试过设置为512，无效果
    );

    PasswordCredentialModel pcm = encoder.encodedCredential(password, Pbkdf2Sha512PasswordHashProviderFactory.DEFAULT_ITERATIONS);

    Date date = new Date();
    pcm.setCreatedDate(date.getTime());
    pcm.setUserLabel("user-spi migration");

    // 绑定凭证到本地用户
    if (!local.credentialManager().isConfiguredFor(input.getType())) {
        try {
            local.credentialManager().createStoredCredential(pcm);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    return valid;
}

问题排查与解决方案 #

1. 核心问题：手动实例化加密提供者导致参数不匹配 #

你手动创建Pbkdf2PasswordHashProvider实例，没有使用Keycloak会话上下文提供的加密服务，会导致以下问题：

• 盐值未自动生成：Keycloak默认加密提供者会生成随机盐，手动实例化后可能缺失盐值，验证时无法匹配
• 加密参数不一致：手动指定的迭代次数、密钥长度可能与当前realm配置的密码策略不匹配

2. 修复方案 #

直接使用Keycloak内置的凭证管理API，交由系统自动处理加密逻辑，避免手动实例化带来的参数差异：

优化后的isValid代码：

@Override
public boolean isValid(RealmModel realm, UserModel user, CredentialInput input) {
    if (!(input instanceof UserCredentialModel)) {
        return false;
    }
    UserCredentialModel cred = (UserCredentialModel) input;
    String password = cred.getValue();

    // 旧系统凭证验证
    String loginOutput = loginCMD(user.getUsername(), password, xForwardedFor);
    boolean valid = !"false".equals(loginOutput);

    if (!valid) {
        return false;
    }

    // 检查本地用户是否存在
    UserModel localUser = UserStoragePrivateUtil.userLocalStorage(session).getUserByUsername(realm, user.getUsername());
    if (localUser != null) {
        return valid;
    }

    // 创建本地用户
    localUser = UserStoragePrivateUtil.userLocalStorage(session).addUser(realm, user.getUsername());
    localUser.setFirstName("firstName");
    localUser.setLastName("lastName");
    localUser.setEmail(user.getUsername());
    localUser.setEnabled(true);
    localUser.setUsername(user.getUsername());

    // 使用Keycloak内置API更新密码，自动处理加密、盐值生成
    try {
        localUser.credentialManager().updateCredential(UserCredentialModel.password(password));
    } catch (Exception e) {
        e.printStackTrace();
        // 凭证创建失败不影响旧系统验证结果，但需记录日志
        return valid;
    }

    return valid;
}

3. 额外检查点 #

• 确认当前realm的密码策略使用的是PBKDF2 SHA512算法，与代码中依赖的加密算法一致
• 查看public.credential表中该用户的credential_data字段，确认包含完整的算法标识、迭代次数、盐值和哈希值
• 确保本地用户的enabled属性设置为true，无其他属性异常

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