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对象,校验失败再抛出认证异常。
调整后的运行流程
- 访问Swagger页面时,所有静态资源、元数据请求会被安全配置直接放行,且不匹配认证过滤器的触发规则,不会执行任何认证逻辑,
attemptAuthentication()方法不会被多次触发。 - 用户在Swagger页面点击「Authorize」输入Key时,仅前端存储Key,无后端请求,不触发认证流程。
- 用户在Swagger页面调用具体业务接口时,请求会自动携带存储的Authorization头,此时匹配认证过滤器的规则,触发对应逻辑完成Key校验。
内容的提问来源于stack exchange,提问作者duppydodah
相关产品推荐
相关产品推荐

