Spring Security：身份验证失败（错误凭证）自定义处理器问题

咱们先直击核心：你已经实现了自定义的AuthenticationFailureHandler，但凭证无效时没触发它，反而返回了默认的401页面，大概率是配置环节没把自定义的FailureHandler正确绑定到Spring Security的过滤链中，或者你的FailureHandler实现有逻辑漏洞。下面一步步帮你排查解决：

一、先确认自定义AuthenticationFailureHandler的实现是否正确 #

确保你的FailureHandler彻底禁用了默认跳转逻辑，明确返回JSON响应。比如这样写：

@Component
public class CustomAuthFailureHandler extends SimpleUrlAuthenticationFailureHandler {

    @Override
    public void onAuthenticationFailure(HttpServletRequest request, HttpServletResponse response, AuthenticationException exception) throws IOException, ServletException {
        // 关闭默认的页面跳转行为
        super.setDefaultTargetUrl(null);
        super.setUseForward(false);

        // 设置响应头为JSON格式
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);

        // 构造自定义失败响应体
        Map<String, Object> responseBody = new HashMap<>();
        responseBody.put("code", 401);
        responseBody.put("message", "登录失败：" + exception.getMessage());
        responseBody.put("timestamp", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));

        // 把JSON写入响应
        ObjectMapper objectMapper = new ObjectMapper();
        objectMapper.writeValue(response.getWriter(), responseBody);
    }
}

这里关键是要禁用默认跳转，不然Spring Security会优先执行页面跳转，忽略你的JSON响应逻辑。

二、确保Spring Security配置中正确绑定自定义FailureHandler #

这一步最容易被忽略！在你的SecurityConfig配置类里，必须明确在表单登录（或你用的认证方式）中指定failureHandler，否则Spring Security会用默认的实现。示例配置如下：

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Autowired
    private CustomAuthFailureHandler customAuthFailureHandler;

    @Autowired
    private CustomAuthSuccessHandler customAuthSuccessHandler;

    @Autowired
    private CustomAuthenticationEntryPoint customAuthenticationEntryPoint;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .anyRequest().authenticated()
            )
            .formLogin(form -> form
                .loginProcessingUrl("/api/login") // 你的登录接口路径
                .successHandler(customAuthSuccessHandler) // 绑定成功处理器
                .failureHandler(customAuthFailureHandler) // 绑定失败处理器，这步必须有！
                .permitAll()
            )
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint(customAuthenticationEntryPoint)
            )
            .csrf(csrf -> csrf.disable()); // 前后端分离项目通常需要禁用CSRF

        return http.build();
    }
}

注意：如果是前后端分离项目，别配置loginPage，否则会跳转到默认登录页面，干扰JSON响应。

三、特殊场景排查：HTTP Basic认证的情况 #

如果你的项目同时用了HTTP Basic认证，凭证无效时可能会触发AuthenticationEntryPoint而不是AuthenticationFailureHandler。这时候可以在EntryPoint里做区分处理：

@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    @Autowired
    private CustomAuthFailureHandler customAuthFailureHandler;

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException, ServletException {
        // 判断是否是登录接口的请求
        if ("/api/login".equals(request.getRequestURI())) {
            // 登录请求的失败交给FailureHandler处理
            customAuthFailureHandler.onAuthenticationFailure(request, response, authException);
        } else {
            // 其他未认证请求返回通用JSON
            response.setContentType("application/json;charset=UTF-8");
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            Map<String, Object> responseBody = new HashMap<>();
            responseBody.put("code", 401);
            responseBody.put("message", "请先完成登录");
            responseBody.put("timestamp", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
            ObjectMapper objectMapper = new ObjectMapper();
            objectMapper.writeValue(response.getWriter(), responseBody);
        }
    }
}

四、调试小技巧 #

1. 在onAuthenticationFailure方法里打个断点或加日志，确认方法是否被调用。如果没触发，说明配置没生效，回头检查SecurityConfig的绑定。
2. 开启Spring Security的DEBUG日志（配置org.springframework.security为DEBUG级别），能看到认证流程的每一步，快速定位哪一步没触发自定义处理器。

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