如何在Keycloak中自定义并加载SPI？Docker环境加载失败求助

一、SPI加载失败的排查步骤 #

1. 验证Jar包结构与配置文件 #

• 检查META-INF/services目录下的两个配置文件：
  • org.keycloak.provider.Spi：确认内容为org.example.myspi.ExampleSpi，无多余空格或换行
  • org.keycloak.provider.ProviderFactory：确认内容为org.example.myspi.MyProviderFactory
• 使用命令验证Jar包内容：

  jar tf your-spi.jar
  

  确保上述两个配置文件路径正确且存在。

2. Docker容器内操作正确性 #

• 将Jar上传至/opt/keycloak/providers后，必须执行构建命令（Keycloak 17+版本）：

  /opt/keycloak/bin/kc.sh build
  

• 执行构建后必须重启Keycloak容器，否则新的SPI不会被加载。
• 查看Keycloak启动日志，搜索example、MyProviderFactory等关键词，排查是否存在类找不到、初始化异常等错误。

3. 依赖版本兼容性 #

• 确保自定义SPI的Keycloak依赖（如keycloak-core、keycloak-server-spi）与容器内Keycloak版本完全一致，版本不兼容会导致类加载失败。
• 若SPI依赖外部HTTP客户端（如Apache HttpClient、OkHttp），需将依赖打包进Jar包（可使用maven-shade-plugin或maven-assembly-plugin构建胖包）。

4. SPI代码实现验证 #

• ExampleSpi的isInternal()返回false符合外部SPI的要求，无需修改。
• 在MyProviderFactory的init()或postInit()方法中添加日志输出，验证是否被加载：

  import org.jboss.logging.Logger;
  
  @Override
  public void init(Config.Scope config) {
      Logger.getLogger(getClass()).info("MyProviderFactory initialized successfully");
  }
  

• 启动Keycloak后查看日志，若存在该日志则说明SPI已被加载。

二、Keycloak内置HTTP请求方案 #

Keycloak没有专门的HTTP请求SPI，但可以通过以下方式实现HTTP调用：

1. 使用Keycloak内置工具类 #

通过KeycloakSession获取内置HttpClient：

import org.keycloak.services.util.HttpClientUtil;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;

// 在Provider的create方法或业务逻辑中
HttpClient httpClient = HttpClientUtil.createHttpClient(session.getContext().getRealm());
HttpGet request = new HttpGet("https://your-external-service/api");
// 执行请求逻辑

2. 集成第三方HTTP客户端 #

直接在SPI中引入OkHttp、Apache HttpClient等依赖，打包进Jar包后即可使用，示例（OkHttp）：

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

// 业务逻辑中
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
        .url("https://your-external-service/api")
        .build();
try (Response response = client.newCall(request).execute()) {
    // 处理响应
} catch (Exception e) {
    // 异常处理
}

三、本地预验证建议 #

在部署到Docker前，先在本地Keycloak实例中测试SPI：

1. 将Jar放入本地Keycloak的providers目录
2. 执行kc.sh build并启动Keycloak
3. 查看日志确认SPI加载成功后，再部署到Docker环境

内容的提问来源于stack exchange，提问作者Дмитрий