如何在KeyCloak中更换默认的TokenIntrospectionProvider

要让自定义的TokenIntrospectionProvider生效，需确保SPI（服务提供者接口）的配置和部署流程完全正确，以下是具体步骤：

1. 完善自定义实现类 #

你需要同时实现两个核心接口：

• TokenIntrospectionProvider：实现令牌 introspect 的业务逻辑，包含更新lastAccess的代码
• TokenIntrospectionProviderFactory：负责创建自定义Provider实例，同时要设置唯一ID（管理UI中显示的名称就是这个ID）

示例代码片段：

public class CustomTokenIntrospectionProvider implements TokenIntrospectionProvider {
    private final KeycloakSession session;

    public CustomTokenIntrospectionProvider(KeycloakSession session) {
        this.session = session;
    }

    @Override
    public IntrospectionResponse introspect(String token, String tokenTypeHint, OAuth2Request request) {
        // 可先调用默认实现逻辑（按需调整）
        IntrospectionResponse response = session.getProvider(TokenIntrospectionProvider.class, "default").introspect(token, tokenTypeHint, request);
        
        // 更新lastAccess字段
        if (response.isActive()) {
            UserSessionModel userSession = session.getContext().getUserSession();
            if (userSession != null) {
                userSession.setLastSessionRefresh(session.timestamp());
            }
        }
        return response;
    }

    @Override
    public void close() {}
}

public class CustomTokenIntrospectionProviderFactory implements TokenIntrospectionProviderFactory {
    @Override
    public TokenIntrospectionProvider create(KeycloakSession session) {
        return new CustomTokenIntrospectionProvider(session);
    }

    @Override
    public String getId() {
        return "custom-introspection-provider"; // 该ID需与管理UI中显示的名称一致
    }

    @Override
    public void init(Config.Scope config) {}

    @Override
    public void postInit(KeycloakSessionFactory factory) {}

    @Override
    public void close() {}
}

2. 配置SPI服务文件 #

在项目的src/main/resources/META-INF/services目录下，创建名为org.keycloak.services.resource.TokenIntrospectionProviderFactory的文件，文件内容为自定义工厂类的全限定名：

com.yourpackage.CustomTokenIntrospectionProviderFactory

3. 打包部署 #

• 将项目打包成JAR文件
• 将JAR复制到Keycloak服务器的providers目录下
• 执行Keycloak构建命令，让服务器加载新Provider：

  # Linux/macOS
  ./kc.sh build
  
  # Windows
  kc.bat build
  

• 重启Keycloak服务

4. 设置默认Provider #

登录Keycloak管理UI：

1. 进入目标Realm
2. 点击左侧菜单「Realm Settings」→「Providers」标签页
3. 在「Token Introspection」列表中找到你的自定义Provider（ID对应工厂类getId()返回值）
4. 点击「Set as default」按钮

5. 验证生效 #

可在自定义Provider的introspect方法中添加日志输出，或通过调试断点，调用introspect端点后检查日志是否打印，同时查看会话的lastAccess字段是否被更新。

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