Keycloak自定义用户存储SPI如何获取原大小写敏感用户名

针对你遇到的Keycloak自动将用户名转小写，导致用户联合SPI调用外部API找不到用户的问题，以下是几个可行的替代方案：

方案1：在用户联合SPI中直接获取原始输入的用户名 #

不需要修改全局配置，直接在你的SPI实现中抓取用户登录时输入的原始用户名。在validateCredentials方法里，通过Keycloak会话上下文获取HTTP请求中的原始用户名参数：

@Override
public boolean validateCredentials(RealmModel realm, UserModel user, UserCredentialModel credential, KeycloakSession session) {
    // 从请求中获取未被转换的原始用户名
    HttpServletRequest request = session.getContext().getHttpServletRequest();
    String originalUsername = request.getParameter("username");
    
    // 使用原始用户名调用外部用户API做验证
    boolean isValid = externalUserApi.validate(originalUsername, credential.getChallengeResponse());
    
    if (isValid) {
        // 同步外部用户信息到Keycloak（按需执行）
        syncUserInfo(realm, user, originalUsername);
    }
    return isValid;
}

方案2：自定义用户名转换器（Username Converter） #

通过实现Keycloak的UsernameConverter SPI，针对目标用户联合提供商禁用用户名小写转换：

1. 实现org.keycloak.storage.user.UsernameConverter接口：

public class CaseSensitiveConverter implements UsernameConverter {
    @Override
    public String convert(String username) {
        // 直接返回原始用户名，不做大小写处理
        return username;
    }
}

2. 将代码打包成JAR，放到Keycloak的providers目录（Docker部署可通过挂载本地目录到容器/opt/keycloak/providers实现）。
3. 登录Keycloak管理控制台，进入目标用户联合提供商的配置页，找到Username Converter选项，选择你自定义的转换器即可生效。

方案3：修正缓存配置文件（解决启动错误） #

之前替换cache-ispn.xml出现启动报错，是因为配置文件中缺少users缓存的定义。针对Keycloak 20.0.1版本，正确的缓存配置需包含users节点：

<?xml version="1.0" encoding="UTF-8"?>
<infinispan xmlns="urn:infinispan:config:12.1">
    <cache-container name="keycloak">
        <!-- 保留原有默认缓存配置 -->
        <cache name="users">
            <encoding>
                <key media-type="text/plain"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <memory max-count="10000"/>
            <expiration lifespan="86400000"/>
        </cache>
        <!-- 保留其他缓存配置 -->
    </cache-container>
</infinispan>

Docker部署时，将修改后的配置文件挂载到容器的/opt/keycloak/conf/cache-ispn.xml路径，启动命令示例：

docker run -d \
  -p 8080:8080 \
  -v ./cache-ispn.xml:/opt/keycloak/conf/cache-ispn.xml \
  quay.io/keycloak/keycloak:20.0.1 start-dev

此方案为全局修改，会影响所有用户存储的用户名处理逻辑，需谨慎使用。

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