Keycloak 23.0.x创建用户时遇旧credentials格式错误及空指针问题

问题现象 #

创建用户时触发两类问题：

• 警告日志：Using deprecated 'credentials' format in JSON representation for user 'Sapil'
• 空指针异常：java.lang.NullPointerException: Cannot invoke "java.lang.Integer.intValue()" because the return value of "org.keycloak.representations.idm.CredentialRepresentation.getHashIterations()" is null

本质是你在使用已被弃用的旧版credentials格式，Keycloak 23.x在兼容处理旧格式时，会尝试读取已标记为弃用的hashIterations字段，但该字段已无法被设置，最终导致null值触发NPE。

解决方案 #

直接切换到Keycloak官方推荐的新版用户创建格式，完全避开旧的哈希相关字段：

1. REST API 请求示例（推荐写法）

无需使用credentials数组，直接在用户JSON中指定password字段：

{
  "username": "Sapil",
  "enabled": true,
  "password": "your-secure-password"
}

Keycloak会自动处理密码的哈希、迭代次数等安全逻辑，无需手动配置。

2. Java Admin Client 示例（推荐写法）

直接调用UserRepresentation的setPassword方法，无需构造CredentialRepresentation：

UserRepresentation user = new UserRepresentation();
user.setUsername("Sapil");
user.setEnabled(true);
user.setPassword("your-secure-password");

// 调用Keycloak Admin API创建用户
keycloak.realm("your-realm").users().create(user);

3. 若必须使用credentials数组（不推荐）

如果因特殊需求必须保留credentials数组，只传递必要字段，不要包含任何已弃用的哈希相关属性：

{
  "username": "Sapil",
  "enabled": true,
  "credentials": [
    {
      "type": "password",
      "value": "your-secure-password",
      "temporary": false
    }
  ]
}

注意事项 #

• 旧版credentials格式（包含hashAlgorithm、hashIterations、salt等字段）已被官方标记为弃用，未来版本会完全移除，务必尽快迁移到新格式。
• Keycloak 23.x对旧格式的兼容存在bug，即使想补全hashIterations字段，该方法也已被标记为弃用无法设置，所以唯一可行的解决方式是切换新格式。

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