Spring Security自定义异常响应：在过滤器链中处理认证与授权失败-java教程-PHP中文网

Spring Security自定义异常响应：在过滤器链中处理认证与授权失败

spring security的认证与授权异常发生在控制器层之前，无法被`@controlleradvice`捕获。本文将指导如何通过实现`authenticationentrypoint`和`accessdeniedhandler`接口，在spring security过滤器链中定制认证失败和授权拒绝的响应体。通过采用委托模式（delegate approach），可以将这些异常转发给spring mvc的`handlerexceptionresolver`处理，从而利用`@controlleradvice`统一生成友好的json错误信息，提升api的用户体验和错误处理一致性。

Spring Security异常处理机制概述

在Spring Boot应用中，我们通常会使用@ControllerAdvice结合@ExceptionHandler来集中处理控制器层抛出的各种异常，并返回统一的JSON错误响应。然而，Spring Security的过滤器链（Filter Chain）在请求到达控制器之前就已经执行。这意味着，如果在认证（Authentication）或授权（Authorization）阶段发生异常，例如用户未提供有效的凭证（AuthenticationException）或已认证用户但无权访问某个资源（AccessDeniedException），这些异常将不会被@ControllerAdvice捕获。

Spring Security通过ExceptionTranslationFilter来处理这些发生在过滤器链中的特定异常。当ExceptionTranslationFilter捕获到AuthenticationException或AccessDeniedException时，它会委托给相应的处理器来生成响应：

对于AuthenticationException（例如，用户未登录或提供的凭证无效），ExceptionTranslationFilter会调用配置的AuthenticationEntryPoint。
对于AccessDeniedException（例如，已登录用户尝试访问其无权访问的资源），ExceptionTranslationFilter会调用配置的AccessDeniedHandler。

默认情况下，这些处理器可能会重定向到登录页面或返回简单的HTTP状态码。为了实现API风格的JSON错误响应，我们需要自定义这些处理器。

定制认证失败响应：AuthenticationEntryPoint

AuthenticationEntryPoint接口定义了一个commence方法，当未认证用户尝试访问受保护资源，或认证过程中发生异常时，此方法会被调用。

直接写入响应体

最直接的方式是在commence方法中手动构建JSON并写入HttpServletResponse。

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) throws IOException, ServletException {
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding("UTF-8");

        Map<String, Object> errorDetails = new HashMap<>();
        errorDetails.put("status", HttpStatus.UNAUTHORIZED.value());
        errorDetails.put("error", "Unauthorized");
        errorDetails.put("message", "认证失败: " + authException.getMessage());
        errorDetails.put("path", request.getRequestURI());

        response.getWriter().write(objectMapper.writeValueAsString(errorDetails));
    }
}

登录后复制

委托模式（Delegate Approach）

为了保持错误处理的一致性并利用@ControllerAdvice的强大功能（如统一的JSON序列化、国际化等），推荐使用委托模式。这种方法通过将异常重新转发给Spring MVC的HandlerExceptionResolver，使得@ControllerAdvice中的@ExceptionHandler能够捕获并处理这些异常。

首先，定义一个简单的错误响应DTO：

public class ErrorResponse {
    private String code;
    private String message;
    private int status;

    public ErrorResponse(String code, String message, int status) {
        this.code = code;
        this.message = message;
        this.status = status;
    }

    // Getters and Setters
    public String getCode() { return code; }
    public void setCode(String code) { this.code = code; }
    public String getMessage() { return message; }
    public void setMessage(String message) { this.message = message; }
    public int getStatus() { return status; }
    public void setStatus(int status) { this.status = status; }
}

登录后复制

然后，创建自定义的AuthenticationEntryPoint，注入HandlerExceptionResolver：

百度文心百中

百度大模型语义搜索体验中心

查看详情

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerExceptionResolver;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Component
public class RestAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final HandlerExceptionResolver handlerExceptionResolver;

    // 注入Spring MVC的HandlerExceptionResolver，通常是ExceptionHandlerExceptionResolver
    public RestAuthenticationEntryPoint(@Qualifier("handlerExceptionResolver") HandlerExceptionResolver handlerExceptionResolver) {
        this.handlerExceptionResolver = handlerExceptionResolver;
    }

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) throws IOException, ServletException {
        // 将AuthenticationException委托给HandlerExceptionResolver处理
        // 这样，@ControllerAdvice中的@ExceptionHandler就能捕获到这个异常
        handlerExceptionResolver.resolveException(request, response, null, authException);
    }
}

登录后复制

注意：@Qualifier("handlerExceptionResolver")确保注入的是Spring MVC用于处理@ExceptionHandler的那个HandlerExceptionResolver实例。

定制授权拒绝响应：AccessDeniedHandler

AccessDeniedHandler接口定义了一个handle方法，当已认证用户尝试访问其没有权限的资源时，此方法会被调用。

与AuthenticationEntryPoint类似，我们可以选择直接写入响应体或使用委托模式。为了保持一致性，同样推荐使用委托模式。

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerExceptionResolver;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Component
public class RestAccessDeniedHandler implements AccessDeniedHandler {

    private final HandlerExceptionResolver handlerExceptionResolver;

    public RestAccessDeniedHandler(@Qualifier("handlerExceptionResolver") HandlerExceptionResolver handlerExceptionResolver) {
        this.handlerExceptionResolver = handlerExceptionResolver;
    }

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                       AccessDeniedException accessDeniedException) throws IOException, ServletException {
        // 将AccessDeniedException委托给HandlerExceptionResolver处理
        handlerExceptionResolver.resolveException(request, response, null, accessDeniedException);
    }
}

登录后复制

全局异常处理器：@ControllerAdvice

在实现了委托模式后，我们需要一个@ControllerAdvice来捕获这些被转发的异常，并生成统一的JSON响应。

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.core.AuthenticationException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(AuthenticationException.class)
    @ResponseStatus(HttpStatus.UNAUTHORIZED)
    public ResponseEntity<ErrorResponse> handleAuthenticationException(AuthenticationException ex) {
        // 根据AuthenticationException类型和信息构建具体的ErrorResponse
        return new ResponseEntity<>(new ErrorResponse("AUTH_001", "认证失败: " + ex.getMessage(), HttpStatus.UNAUTHORIZED.value()), HttpStatus.UNAUTHORIZED);
    }

    @ExceptionHandler(AccessDeniedException.class)
    @ResponseStatus(HttpStatus.FORBIDDEN)
    public ResponseEntity<ErrorResponse> handleAccessDeniedException(AccessDeniedException ex) {
        // 根据AccessDeniedException类型和信息构建具体的ErrorResponse
        return new ResponseEntity<>(new ErrorResponse("AUTH_002", "权限不足: " + ex.getMessage(), HttpStatus.FORBIDDEN.value()), HttpStatus.FORBIDDEN);
    }

    // 可以添加其他通用异常处理器
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ResponseEntity<ErrorResponse> handleGenericException(Exception ex) {
        return new ResponseEntity<>(new ErrorResponse("SYS_001", "系统内部错误: " + ex.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR.value()), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

登录后复制

Spring Security配置整合

最后一步是将自定义的AuthenticationEntryPoint和AccessDeniedHandler注册到Spring Security的配置中。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private final RestAuthenticationEntryPoint authenticationEntryPoint;
    private final RestAccessDeniedHandler accessDeniedHandler;

    // 注入自定义的处理器
    public SecurityConfig(RestAuthenticationEntryPoint authenticationEntryPoint,
                          RestAccessDeniedHandler accessDeniedHandler) {
        this.authenticationEntryPoint = authenticationEntryPoint;
        this.accessDeniedHandler = accessDeniedHandler;
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable()) // 通常RESTful API会禁用CSRF
            .authorizeHttpRequests(authorize -> authorize
                .antMatchers("/public/**").permitAll() // 允许公共访问的路径
                .anyRequest().authenticated() // 其他所有请求需要认证
            )
            .exceptionHandling(exceptionHandling -> exceptionHandling
                .authenticationEntryPoint(authenticationEntryPoint) // 配置认证失败处理器
                .accessDeniedHandler(accessDeniedHandler)     // 配置授权拒绝处理器
            )
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS) // RESTful API通常无状态
            );
        return http.build();
    }
}

登录后复制

总结

通过上述步骤，我们成功地在Spring Security过滤器链中定制了认证失败和授权拒绝的响应体。采用委托模式，将AuthenticationException和AccessDeniedException转发给HandlerExceptionResolver，使得@ControllerAdvice能够统一处理这些异常，从而确保API在任何错误场景下都能返回一致、友好的JSON错误响应。这种方法极大地提升了API的健壮性和可维护性，为前端应用提供了统一的错误处理机制。

以上就是Spring Security自定义异常响应：在过滤器链中处理认证与授权失败的详细内容，更多请关注php中文网其它相关文章！