Keycloak Admin Client创建用户遇userProfileMetadata未识别错误

核心问题 #

你用的Keycloak Admin Client版本（25.0.2）和服务器版本（16.1.1）版本差距过大，高版本客户端会自动在请求体中添加userProfileMetadata字段，但低版本Keycloak服务器不支持这个字段，导致400错误。之前的Jackson忽略配置没用，是因为这个字段是客户端内部序列化时自动注入的，并非你手动构造的JSON内容。

可行解决方案 #

1. 对齐Keycloak依赖与服务器版本（推荐） #

这是最彻底的解决方法：把keycloak-spring-boot-starter和keycloak-admin-client的版本降到和服务器一致的16.1.1。

修改pom.xml（Maven）：

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-spring-boot-starter</artifactId>
    <version>16.1.1</version>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>16.1.1</version>
</dependency>

或者build.gradle（Gradle）：

implementation 'org.keycloak:keycloak-spring-boot-starter:16.1.1'
implementation 'org.keycloak:keycloak-admin-client:16.1.1'

版本对齐后，客户端不会生成服务器不识别的字段，直接解决报错。

2. 自定义Jackson序列化拦截（临时方案） #

如果暂时无法降级依赖，可强制拦截序列化过程，移除自动添加的userProfileMetadata字段：

• 创建自定义ObjectMapper配置类，针对UserRepresentation做特殊处理：

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.databind.module.SimpleModule;
import com.fasterxml.jackson.databind.ser.BeanSerializerModifier;
import com.fasterxml.jackson.databind.ser.PropertyWriter;
import org.keycloak.representations.idm.UserRepresentation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.List;
import java.util.stream.Collectors;

@Configuration
public class KeycloakJacksonConfig {

    @Bean
    public ObjectMapper keycloakObjectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.disable(SerializationFeature.FAIL_ON_UNWRAPPED_TYPE_IDENTIFIERS);

        // 移除userProfileMetadata字段
        SimpleModule module = new SimpleModule();
        module.setSerializerModifier(new BeanSerializerModifier() {
            @Override
            public List<PropertyWriter> changeProperties(SerializationConfig config, BeanDescription beanDesc, List<PropertyWriter> properties) {
                if (beanDesc.getBeanClass() == UserRepresentation.class) {
                    return properties.stream()
                            .filter(p -> !"userProfileMetadata".equals(p.getName()))
                            .collect(Collectors.toList());
                }
                return super.changeProperties(config, beanDesc, properties);
            }
        });

        mapper.registerModule(module);
        return mapper;
    }
}

• 创建Keycloak客户端时指定使用这个自定义ObjectMapper：

import org.keycloak.admin.client.Keycloak;
import org.keycloak.admin.client.KeycloakBuilder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.jboss.resteasy.client.jaxrs.ResteasyClientBuilder;
import com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider;

@Component
public class KeycloakClient {

    @Autowired
    private ObjectMapper keycloakObjectMapper;

    public Keycloak getKeycloakClient() {
        return KeycloakBuilder.builder()
                .serverUrl("你的Keycloak服务器地址")
                .realm("目标Realm名称")
                .clientId("admin-cli")
                .username("管理员账号")
                .password("管理员密码")
                .resteasyClient(new ResteasyClientBuilder().register(new JacksonJsonProvider(keycloakObjectMapper)).build())
                .build();
    }
}

3. 直接发送原始HTTP请求（终极临时方案） #

如果以上方法都无效，可以绕过Keycloak Admin Client，用RestTemplate发送纯JSON请求：

import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestTemplate;

public class KeycloakUserCreator {

    public void createUser(String adminToken) {
        RestTemplate restTemplate = new RestTemplate();
        
        // 构造不含多余字段的用户JSON
        String userJson = "{\"username\":\"test-user\",\"email\":\"test@example.com\",\"enabled\":true,\"credentials\":[{\"type\":\"password\",\"value\":\"123456\",\"temporary\":false}]}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setBearerAuth(adminToken);
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        ResponseEntity<String> response = restTemplate.postForEntity(
                "http://你的Keycloak地址/auth/admin/realms/目标Realm/users",
                userJson,
                String.class
        );
        
        if (response.getStatusCode().is2xxSuccessful()) {
            // 用户创建成功
        }
    }
}

注意事项 #

• 优先选择版本对齐方案，版本差异会引发更多潜在兼容性问题，不止这一个字段。
• 若必须使用高版本客户端，需全面测试其他API是否存在类似兼容问题。

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