Spring Boot+Keycloak中如何保证sub与username的唯一性一致性？

核心问题分析 #

你当前的逻辑同时把sub和username作为用户身份的判定依据，但Keycloak中sub是用户的永久唯一标识符，而username是可修改的属性。当出现"同一sub对应不同username"或"同一username对应不同sub"的情况时，现有逻辑会触发错误，但实际上前者属于用户信息更新场景，后者属于不同用户复用了相同username（若业务未强制username全局唯一）。

优化建模与实现方案 #

1. 调整数据库约束 #

将sub字段设置为唯一约束（或主键），确保每个sub对应唯一本地用户；username字段可保留普通索引，无需强制唯一（除非业务明确要求username本地唯一）。

2. 修改用户加载逻辑 #

优先通过sub定位用户，因为sub是Keycloak用户的唯一身份标识：

• 若找到用户：同步JWT中的最新username到本地数据库（适配Keycloak中username被修改的场景）
• 若未找到用户：创建新用户，存储sub和当前username

优化后的代码示例 #

public User loadUser(@Valid UserCreate userCreate) {
    // 优先通过唯一标识sub查询用户
    Optional<User> optionalUser = userRepository.findBySub(userCreate.sub());
    
    if (optionalUser.isPresent()) {
        User existingUser = optionalUser.get();
        // 同步Keycloak中更新后的username
        if (!existingUser.getUsername().equals(userCreate.username())) {
            existingUser.setUsername(userCreate.username());
            userRepository.save(existingUser);
        }
        return existingUser;
    }
    
    // 可选：若业务要求username本地唯一，新增前检查是否被占用
    if (userRepository.existsByUsername(userCreate.username())) {
        throw new IllegalArgumentException(String.format("Username %s is already used by another user", userCreate.username()));
    }
    
    // 创建新用户
    User user = User.builder()
            .username(userCreate.username())
            .sub(userCreate.sub())
            .build();
    return userRepository.save(user);
}

场景处理说明 #

针对你提到的三个用户场景：

• 用户A（sub=s1，username=u4）已存在
• 用户B（sub=s4，username=u1）已存在
• 用户C（sub=s1，username=u1）请求到达：
  此时通过sub=s1找到用户A，直接更新其username为u1，返回更新后的用户A，不会触发错误，完全适配"用户在Keycloak中修改了username"的真实业务场景。

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