You need to enable JavaScript to run this app. Spring Boot集成Springfox Swagger UI认证过滤器异常触发排查
优惠活动
大模型
产品
解决方案
定价
更多

Spring Boot集成Springfox Swagger UI认证过滤器异常触发排查

问题核心根因
  • 当前自定义SimpleAuthFilter的请求匹配规则为/**,而AbstractAuthenticationProcessingFilter的执行逻辑是:只要请求匹配预设的RequestMatcher,就会自动执行attemptAuthentication()方法,与后续的授权规则无关。
  • 因此所有请求——包括Swagger静态资源、接口元数据的GET请求——都会被过滤器拦截触发认证流程,完全不符合“仅提交密钥时触发认证”的设计预期。
  • 之前的方案没有生效,本质原因是仅在授权配置层面对Swagger路径做了permitAll设置,但没有从过滤器的匹配规则层面排除Swagger相关路径,导致过滤器依然会拦截所有请求。
具体调整方案

1. 重构SimpleAuthFilter的触发匹配规则

将原来匹配所有路径的规则,替换为「仅当请求不属于Swagger资源、且携带Authorization认证头时,才触发认证流程」:

@Bean
public SimpleAuthFilter filter() {
    RequestMatcher authTriggerMatcher = request -> {
        String uri = request.getRequestURI();
        // 直接排除所有Swagger相关资源路径
        boolean isSwaggerResource = uri.startsWith("/swagger-ui")
                || uri.equals("/swagger-ui.html")
                || uri.startsWith("/swagger-resources")
                || uri.equals("/v2/api-docs");
        if (isSwaggerResource) {
            return false;
        }
        // 非Swagger请求,仅在携带Authorization认证头时触发认证
        String authHeader = request.getHeader("Authorization");
        return authHeader != null && !authHeader.isBlank();
    };
    return new SimpleAuthFilter(authTriggerMatcher);
}

调整后,Swagger相关的所有静态资源、元数据请求都不会匹配过滤器规则,自然不会触发attemptAuthentication()方法。

2. 配置Swagger资源的匿名访问权限

在Spring Security的授权配置中,将所有Swagger相关路径设为允许匿名访问,确保页面加载环节不会被安全链路拦截:

@Override
public void configure(HttpSecurity sec) throws Exception {
    http.sessionManagement()
        .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
        .and()
        .addFilterBefore(filter(), AnonymousAuthenticationFilter.class)
        .authorizeRequests()
            // 放行所有Swagger相关路径
            .antMatchers(
                "/swagger-ui/**",
                "/swagger-ui.html",
                "/swagger-resources/**",
                "/v2/api-docs"
            ).permitAll()
            // 其余业务接口需通过认证
            .anyRequest().authenticated()
        .and()
        .csrf().disable();
}

3. 修正资源配置的常见误区

  • 不要为了映射Swagger静态资源继承WebMvcConfigurationSupport,该类会覆盖Spring Boot的自动资源配置,反而导致Swagger页面加载异常。如果需要自定义资源映射,实现WebMvcConfigurer接口即可。
  • 明确Swagger UI的交互逻辑:前端的「Authorize」按钮仅会将用户输入的API Key存储在前端全局状态中,不会向后端发送独立的认证请求,所有认证校验都发生在后续携带API Key的业务接口调用环节,无需为Authorize动作单独配置后端触发规则。

4. 调整认证管理器的实际校验逻辑

当前测试用的MyAuthManager实现为直接抛出认证异常,实际落地时需要替换为真实的API Key校验逻辑:从请求头中提取Key,与系统配置的有效Key做对比,校验通过则返回已认证的Authentication对象,校验失败再抛出认证异常。

调整后的运行流程
  1. 访问Swagger页面时,所有静态资源、元数据请求会被安全配置直接放行,且不匹配认证过滤器的触发规则,不会执行任何认证逻辑,attemptAuthentication()方法不会被多次触发。
  2. 用户在Swagger页面点击「Authorize」输入Key时,仅前端存储Key,无后端请求,不触发认证流程。
  3. 用户在Swagger页面调用具体业务接口时,请求会自动携带存储的Authorization头,此时匹配认证过滤器的规则,触发对应逻辑完成Key校验。

内容的提问来源于stack exchange,提问作者duppydodah

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.14 15:54:02