使用Keycloak Admin Client API注册用户时提示username required错误

向/register端点发送以下请求体的POST请求注册用户时失败：

{
    "username": "asas",
    "email": "asas@gmail.com",
    "password": "asas"
}

日志报错如下：

2025-02-05T15:36:28.299+07:00  INFO 42339 --- [auth-service] [nio-8081-exec-1] o.f.user.controller.AuthController       : Received registration request for username: asas
2025-02-05T15:36:28.299+07:00  INFO 42339 --- [auth-service] [nio-8081-exec-1] o.f.user.listener.AuthEventListener      : Processing user registration for username: asas
2025-02-05T15:36:28.300+07:00 ERROR 42339 --- [auth-service] [nio-8081-exec-1] o.f.user.listener.AuthEventListener      : Error registering user in Keycloak: username required

已尝试操作 #

• 检查请求体：确认username、email和password参数已正确传递
• 检查UserRegisteredEvent类：字段定义与映射无问题
• 检查Keycloak Admin API配置：用户创建、角色及认证相关配置正常

代码信息 #

配置文件 #

keycloak:
  realm: <your-realm-name>
  auth-server-url: http://localhost:9090/
  resource: <your-resource-name>
  credentials:
    client-id: <your-client-id>
    secret: <your-secret>
  use-resource-role-mappings: true

AuthController #

@RestController
@RequestMapping("/api/v1/auth")
@RequiredArgsConstructor
public class AuthController {

    private final AuthEventListener userEventListener;
    private static final Logger logger = LoggerFactory.getLogger(AuthController.class);

    @PostMapping("/register")
    public ResponseEntity<?> register(@RequestBody UserRegisteredEvent event) {
        logger.info("Received registration request for username: {}", event.getUsername());
        return userEventListener.handleUserRegistration(event);
    }

    @PostMapping("/login")
    public ResponseEntity<?> login(@RequestBody UserLoginEvent event) {
        return userEventListener.handleUserLogin(event);
    }
}

AuthEventListener #

@Service
@RequiredArgsConstructor
public class AuthEventListener {

    private final KafkaTemplate<String, UserRegisteredEvent> userRegisteredTemplate;
    private final AuthService authService;

    private static final Logger logger = Logger.getLogger(AuthEventListener.class.getName());

    @KafkaListener(topics = "user-registration", groupId = "auth-service")
    public ResponseEntity<?> handleUserRegistration(UserRegisteredEvent event) {
        logger.info("Processing user registration for username: " + event.getUsername());
        try {
            authService.registerUser(event.getUsername(), event.getEmail(), event.getPassword());
            userRegisteredTemplate.send("user-registered", event);
            logger.info("User successfully registered in Keycloak: " + event.getUsername());
        } catch (Exception e) {
            logger.severe("Error registering user in Keycloak: " + e.getMessage());
        }
        return ResponseEntity.ok().build();
    }
}

AuthService #

@Service
@RequiredArgsConstructor
public class AuthService {

    @Value("${keycloak.auth-server-url}")
    private String keycloakAuthServerUrl;

    @Value("${keycloak.realm}")
    private String keycloakRealm;

    @Value("${keycloak.credentials.client-id}")
    private String keycloakClientId;

    @Value("${keycloak.credentials.secret}")
    private String keycloakClientSecret;

    private static final Logger logger = Logger.getLogger(AuthService.class.getName());

    private Keycloak getAdminKeycloakInstance() {
        return KeycloakBuilder.builder()
                .serverUrl(keycloakAuthServerUrl)
                .realm(keycloakRealm)
                .clientId(keycloakClientId)
                .clientSecret(keycloakClientSecret)
                .build();
    }

    public void registerUser(String username, String email, String password) {
        Keycloak keycloak = getAdminKeycloakInstance();
        RealmResource realmResource = keycloak.realm(keycloakRealm);
        UsersResource usersResource = realmResource.users();

        UserRepresentation user = new UserRepresentation();
        user.setUsername(username);
        user.setEmail(email);
        user.setEnabled(true);

        Response response = usersResource.create(user);
        if (response.getStatus() != 201) {
            throw new RuntimeException("Failed to create user in Keycloak: " + response.getStatusInfo());
        }
        String userId = response.getLocation().getPath().replaceAll(".*/([^/]+)$", "$1");

        CredentialRepresentation credential = new CredentialRepresentation();
        credential.setTemporary(false);
        credential.setType(CredentialRepresentation.PASSWORD);
        credential.setValue(password);
        keycloak.realm(keycloakRealm).users().get(userId).resetPassword(credential);

        RoleRepresentation userRole = realmResource.roles().get("user").toRepresentation();
        keycloak.realm(keycloakRealm).users().get(userId)
                .roles().realmLevel().add(Collections.singletonList(userRole));

        logger.info("User successfully registered in Keycloak: " + username);
    }
}

问题根源 #

日志已打印出Processing user registration for username: asas，说明UserRegisteredEvent中的username正常，但Keycloak返回username required，核心问题有两个：

1. Keycloak Admin API认证方式错误：当前用普通客户端的client-id和secret创建实例，但未指定认证类型，且客户端缺少Admin API调用权限，导致Keycloak无法识别请求合法性。
2. 方法职责混淆：AuthEventListener的handleUserRegistration方法同时标注了@KafkaListener，直接被Controller调用会引发上下文异常，可能导致参数传递异常。

修复步骤 #

1. 修正Keycloak Admin客户端认证 #

修改getAdminKeycloakInstance方法，明确指定认证类型为CLIENT_CREDENTIALS，同时确保Keycloak客户端已启用服务账户并赋予管理权限：

private Keycloak getAdminKeycloakInstance() {
    return KeycloakBuilder.builder()
            .serverUrl(keycloakAuthServerUrl)
            .realm(keycloakRealm)
            .clientId(keycloakClientId)
            .clientSecret(keycloakClientSecret)
            .grantType(OAuth2Constants.CLIENT_CREDENTIALS) // 添加认证类型
            .build();
}

2. 拆分Kafka监听与业务处理方法 #

将handleUserRegistration拆分为Kafka监听方法和普通业务方法，避免直接调用监听方法：

@Service
@RequiredArgsConstructor
public class AuthEventListener {

    private final KafkaTemplate<String, UserRegisteredEvent> userRegisteredTemplate;
    private final AuthService authService;

    private static final Logger logger = Logger.getLogger(AuthEventListener.class.getName());

    // 供Controller调用的业务处理方法
    public ResponseEntity<?> processUserRegistration(UserRegisteredEvent event) {
        logger.info("Processing user registration for username: " + event.getUsername());
        try {
            authService.registerUser(event.getUsername(), event.getEmail(), event.getPassword());
            userRegisteredTemplate.send("user-registered", event);
            logger.info("User successfully registered in Keycloak: " + event.getUsername());
        } catch (Exception e) {
            logger.severe("Error registering user in Keycloak: " + e.getMessage());
            return ResponseEntity.badRequest().body(e.getMessage());
        }
        return ResponseEntity.ok().build();
    }

    // Kafka消息监听方法
    @KafkaListener(topics = "user-registration", groupId = "auth-service")
    public void handleKafkaUserRegistration(UserRegisteredEvent event) {
        processUserRegistration(event);
    }
}

同步修改AuthController调用新的业务方法：

@PostMapping("/register")
public ResponseEntity<?> register(@RequestBody UserRegisteredEvent event) {
    logger.info("Received registration request for username: {}", event.getUsername());
    return userEventListener.processUserRegistration(event);
}

3. 配置Keycloak客户端权限 #

登录Keycloak控制台，进入目标realm：

• 进入Clients，找到你的客户端，开启Service Accounts Enabled
• 进入Service Account Roles，添加realm-management下的manage-users、create-users、manage-realm权限
• 保存配置后重启服务

4. 验证参数传递完整性 #

在registerUser方法中添加日志，确认UserRepresentation参数是否正确：

public void registerUser(String username, String email, String password) {
    Keycloak keycloak = getAdminKeycloakInstance();
    RealmResource realmResource = keycloak.realm(keycloakRealm);
    UsersResource usersResource = realmResource.users();

    UserRepresentation user = new UserRepresentation();
    user.setUsername(username);
    user.setEmail(email);
    user.setEnabled(true);
    
    // 添加参数验证日志
    logger.info("Creating user: username={}, email={}", username, email);
    logger.info("UserRepresentation details: {}", user);

    Response response = usersResource.create(user);
    // ... 剩余代码
}

完成以上步骤后重新测试注册接口，即可正常创建用户。

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