Keycloak用户存储SPI运行时如何获取标识以切换数据库连接

所有用户存储类SPI的实现方法，都会携带KeycloakSession入参，不需要额外的参数传递，就能从这个对象的内置上下文中拿到两类你需要的判定标识：

• 客户端ID标识：调用session.getContext().getClient()获取当前认证流程关联的客户端实例，直接读取getClientId()方法返回的客户端唯一字符串，就能用来匹配对应目标数据库。
  这个上下文会在整个认证、用户查询、凭证校验的全链路自动绑定，不管是登录请求触发的用户匹配，还是校验密码触发的外部用户查询，都能稳定拿到对应值。
• 原始请求详情：如果需要从请求头、查询参数、表单字段中提取自定义的源服务器标识，直接调用session.getContext().getHttpRequest()拿到内嵌的HTTP请求对象，按常规HTTP请求解析逻辑提取需要的字段即可。
  边界提示：如果SPI的调用来源是Keycloak内部逻辑（比如管理员后台搜索用户、定时同步任务），上下文里不会绑定客户端实例，也没有HTTP请求对象，需要提前配置兜底的路由规则匹配默认目标库。

方案1：自定义用户存储SPI对接多外部用户库 #

• 拿到路由标识（客户端ID/自定义请求字段）后，不需要在SPI初始化阶段配置所有数据库的连接，每次执行业务方法时动态根据标识匹配对应的数据库连接配置即可。
• 规避串扰风险：不要把路由标识存在SPI Provider的成员变量中，因为SPI实例会按会话复用，每次方法调用都要重新从session上下文取标识，避免跨请求的配置混淆。
• 示例核心逻辑片段：

// 用户查询方法中动态匹配目标库
@Override
public UserModel getUserByUsername(KeycloakSession session, RealmModel realm, String username) {
    // 优先取客户端ID作为路由key
    ClientModel client = session.getContext().getClient();
    String routeKey = client != null ? client.getClientId() : "default";
    // 从预先配置的映射规则中拿到对应外部库的连接参数
    ExternalDatabaseConn targetDb = routeMapper.getConnByKey(routeKey);
    // 执行对应库的用户查询逻辑
    return targetDb.queryUserByUsername(username, realm.getName());
}

方案2：SPI层集成REST凭证校验逻辑 #

• 标识获取逻辑和上面的用户存储SPI完全通用，不管是自定义认证节点、自定义凭证校验器这类SPI实现，只要方法入参携带KeycloakSession，就能直接复用同一套标识提取逻辑，不需要额外打通请求链路。
• 简化配置的实现思路：拿到路由标识后，从配置中匹配对应目标服务的REST接口地址，把用户输入的凭证、用户名打包发请求完成校验即可，不需要为每个接入服务器单独配置独立的Realm或者用户联邦组件。

• 不要自行基于ThreadLocal实现请求标识的存储传递，Keycloak内置的KeycloakContext已经实现了跨线程的上下文传播，在SPI的异步执行逻辑中也能正确拿到值，自定义ThreadLocal反而会在线程切换时丢失上下文。
• 不要把路由判定逻辑放在SPI的init()初始化方法里，这个方法在SPI组件加载时全局只执行一次，运行时根本没有请求上下文，拿不到任何可用的标识信息。
• 客户端和目标库的映射关系不要硬编码在代码中，可以把映射规则存在Realm的自定义属性里，运行时动态读取调整，不需要修改代码就能变更路由关系。

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