Spring Security集成Keycloak：令牌失效与ClientRegistrationId配置问题

问题背景 #

我开发了一个基于Spring的Vaadin应用，集成Keycloak实现用户认证，并通过Keycloak获取access token调用API。目前认证及API调用功能正常，但存在两个问题：

1. 长时间无操作后refresh token过期，操作应用会抛出Token is not active等异常，必须重启浏览器才能重新登录。
2. 使用WebClient调用API时必须手动设置clientRegistrationId，但Spring官方文档说明该信息可从当前登录用户自动获取。

问题1：为何必须手动设置clientRegistrationId？是否存在配置错误导致自动检测失效？ #

WebClient能自动从当前登录用户获取clientRegistrationId，依赖以下核心配置要点，任意一点缺失都会导致自动检测失效：

1. WebClient必须绑定OAuth2授权客户端管理器 #

你的WebClient配置必须通过OAuth2AuthorizedClientManager和ServletOAuth2AuthorizedClientExchangeFilterFunction构建，不能直接用WebClient.create()创建无认证能力的实例。正确配置示例：

@Bean
WebClient webClient(OAuth2AuthorizedClientManager authorizedClientManager) {
    ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2Filter =
            new ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager);
    // 不要设置setDefaultClientRegistrationId，否则会强制使用默认值，忽略当前用户的客户端信息
    return WebClient.builder()
            .apply(oauth2Filter.oauth2Configuration())
            .build();
}

2. Spring Security上下文必须正确传递到Vaadin线程 #

Vaadin基于UI线程和WebSocket通信，需要确保Spring Security的SecurityContext能在Vaadin的UI线程中被正确获取。可以在调用WebClient前检查：

Authentication auth = SecurityContextHolder.getContext().getAuthentication();
if (!(auth instanceof OAuth2AuthenticationToken)) {
    // 上下文丢失，无法自动识别clientRegistrationId
}

如果上下文丢失，需检查Vaadin配置是否兼容Spring Security，比如是否启用了VaadinWebSecurity（Vaadin 24+），确保请求和UI线程的SecurityContext同步。

3. 正确启用OAuth2客户端配置 #

在SecurityConfiguration中必须启用OAuth2相关配置，示例：

@Configuration
@EnableWebSecurity
public class SecurityConfiguration extends VaadinWebSecurity {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        // 配置Keycloak OAuth2登录
        http.oauth2Login()
                .clientRegistrationRepository(clientRegistrationRepository())
                .authorizedClientService(authorizedClientService());
    }
}

同时确保application.yml/application.properties中的Keycloak客户端配置正确，clientRegistrationId对应配置中的节点名称（比如spring.security.oauth2.client.registration.keycloak中的keycloak就是clientRegistrationId）。

问题2：如何处理令牌超时问题，实现用户操作时自动重定向到登录页？ #

要解决refresh token过期后的自动跳转，需结合Spring Security的令牌管理和Vaadin的异常处理：

1. 配置Spring Security自动令牌刷新 #

确保Spring Security能自动尝试刷新access token，当refresh token也过期时触发重新认证：

• 确保OAuth2AuthorizedClientService正确配置，用于存储和更新用户的令牌信息。
• 在Security配置中启用oauth2Login()，框架会自动处理令牌刷新逻辑，当refresh token过期时，会触发重定向到Keycloak登录页。

2. Vaadin层面捕获令牌失效异常 #

由于Vaadin是单页应用，后台API调用抛出的Token is not active异常不会自动触发页面跳转，需在UI层全局捕获并处理：

• 自定义Vaadin的ErrorHandler全局捕获OAuth2相关异常：

@Bean
ErrorHandler vaadinErrorHandler() {
    return errorEvent -> {
        Throwable cause = errorEvent.getThrowable();
        if (cause instanceof OAuth2AuthorizationException) {
            UI.getCurrent().getPage().setLocation("/oauth2/authorization/keycloak");
        }
    };
}

• 或在具体API调用处捕获异常并跳转：

try {
    webClient.get().uri("/api/data").retrieve().bodyToMono(String.class).block();
} catch (OAuth2AuthorizationException e) {
    UI.getCurrent().getPage().setLocation("/oauth2/authorization/keycloak");
}

3. 额外优化 #

• 前端定时器：在Vaadin前端添加定时器，定期检查当前令牌的过期时间，在access token即将过期且refresh token仍有效时，主动调用后端接口触发令牌刷新，避免用户操作时出错。
• 合理配置Keycloak令牌过期时间：根据业务场景调整refresh token的过期时长，平衡安全性和用户体验。

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