SpringBoot集成Keycloak实现兼容请求头与查询参数的令牌认证

核心逻辑 #

你现有的Keycloak集成配置的鉴权流程，默认仅从Authorization请求头提取Bearer令牌做校验。要兼容URL查询参数传令牌，不需要改动已经写好的KeycloakAuthenticationProvider、KeycloakConfigResolver核心逻辑，仅需扩展Keycloak的令牌提取规则，按照「请求头优先、URL参数兜底」的顺序替换默认提取器即可，完全无侵入。

步骤1：实现自定义令牌提取器 #

实现Keycloak提供的BearerTokenExtractor接口，复用官方默认的请求头提取逻辑，补充URL参数的提取分支：

public class CompositeBearerTokenExtractor implements BearerTokenExtractor {
    // 复用官方默认的请求头提取实现，不重复开发校验逻辑
    private final BearerTokenExtractor headerBasedExtractor = new AuthorizationBearerTokenExtractor();

    @Override
    public AccessToken getAccessToken(HttpFacade.Request request) {
        // 优先从请求头提取令牌，和现有逻辑完全一致
        AccessToken headerToken = headerBasedExtractor.getAccessToken(request);
        if (headerToken != null) {
            return headerToken;
        }
        // 从URL查询参数读取token
        String urlToken = request.getQueryParamValue("token");
        if (urlToken == null || urlToken.isBlank()) {
            return null;
        }
        // 复用官方内置的令牌校验逻辑，保证URL传入的令牌和头传入的令牌校验规则完全一致
        try {
            return AdapterUtils.verifyToken(request, urlToken);
        } catch (VerificationException e) {
            // 令牌不合法直接返回null，走标准401流程
            return null;
        }
    }
}

步骤2：将自定义提取器注入认证链路 #

在Spring Security配置中，替换KeycloakAuthenticationProcessingFilter默认的令牌提取器，不需要修改你现有已配置的Bean：

@Bean
public KeycloakAuthenticationProcessingFilter keycloakAuthFilter(AuthenticationManager authManager) {
    // 保持和官方默认配置一致的请求匹配规则，仅替换提取器
    KeycloakAuthenticationProcessingFilter filter = new KeycloakAuthenticationProcessingFilter(
        authManager,
        new NegatedRequestMatcher(new AntPathRequestMatcher("/error"))
    );
    // 注入自定义的双模式提取器
    filter.setBearerTokenExtractor(new CompositeBearerTokenExtractor());
    // 保持默认的无状态会话策略、认证失败处理逻辑
    filter.setSessionAuthenticationStrategy(new NullAuthenticatedSessionStrategy());
    filter.setAuthenticationFailureHandler(new KeycloakAuthenticationFailureHandler());
    return filter;
}

关键注意点 #

• 安全提示：URL传递的令牌会留存于浏览器历史、网关访问日志、代理服务日志中，仅建议在受控的直链访问场景开启该模式，不要作为通用令牌传递渠道，避免令牌泄露
• 校验一致性：URL提取的令牌走的是和请求头完全相同的校验流程（签名校验、有效期校验、受众校验、角色映射），不存在校验绕过的风险
• 兼容规则：严格遵循请求头优先的提取顺序，只要请求头携带合法令牌，就不会读取URL参数，完全不影响现有已经接入、通过请求头传令牌的客户端调用逻辑
• 现有配置零改动：你已经编写的configureGlobal方法、KeycloakConfigResolver Bean不需要做任何调整，自定义提取器会自动复用你配置的Keycloak连接信息做校验

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