Spring Security自定义认证授权异常响应

本文旨在解决Spring Boot应用中，Spring Security过滤器链抛出的认证（`AuthenticationException`）和授权（`AccessDeniedException`）异常无法被全局异常处理器捕获的问题。我们将深入探讨如何通过实现自定义的`AuthenticationEntryPoint`和`AccessDeniedHandler`接口，在这些安全层级异常发生时，生成结构化的JSON响应体，从而提升用户体验并简化客户端错误处理。

Spring Security过滤器链中的异常处理机制

在Spring Boot应用中，我们通常会通过@ControllerAdvice结合@ExceptionHandler来构建一个全局的异常处理器，以统一处理控制器层抛出的各种异常，并返回友好的JSON错误信息。然而，当涉及到Spring Security的认证（Authentication）和授权（Authorization）失败时，这种机制往往无法生效。

其核心原因在于Spring Security的过滤器链在请求到达任何控制器之前就已经执行。如果在这个阶段发生认证失败（如用户未提供凭据或凭据无效）或授权失败（如用户无权访问特定资源），异常会在过滤器链中被捕获并处理，而不会传递到控制器层，因此也就不会触发@ControllerAdvice中定义的@ExceptionHandler。

默认情况下，Spring Security对于认证失败可能会在响应头中添加WWW-Authenticate信息，但响应体通常是空的或包含一个简单的HTML错误页面。对于现代的RESTful API而言，客户端更期望收到一个结构化的JSON错误响应，以便于解析和展示。为了实现这一目标，我们需要利用Spring Security提供的特定接口来定制这些安全层级的异常响应。

Spring Security主要处理两种类型的安全异常：

1. AuthenticationException：当用户尝试访问受保护资源但尚未认证（或认证失败）时抛出。例如，请求头中缺少Authorization令牌，或者令牌无效。
2. AccessDeniedException：当已认证的用户尝试访问其没有权限的资源时抛出。例如，用户已登录，但其角色不足以访问某个特定API。

定制认证失败响应：实现AuthenticationEntryPoint

AuthenticationEntryPoint接口用于处理AuthenticationException，即当用户尝试访问安全资源但尚未认证（或认证失败）时被调用。它定义了一个commence方法，允许我们自定义响应行为。

基本实现

以下是一个简单的AuthenticationEntryPoint实现，它直接向响应中写入一个JSON错误消息：

import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;

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(HttpServletResponse.SC_UNAUTHORIZED); // 设置HTTP状态码为401
        response.setContentType(MediaType.APPLICATION_JSON_VALUE); // 设置响应内容类型为JSON
        response.setCharacterEncoding("UTF-8");

        Map errorDetails = new HashMap<>();
        errorDetails.put("timestamp", System.currentTimeMillis());
        errorDetails.put("status", HttpServletResponse.SC_UNAUTHORIZED);
        errorDetails.put("error", "Unauthorized");
        errorDetails.put("message", "Authentication failed: " + authException.getMessage());
        errorDetails.put("path", request.getRequestURI());

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

结合@ExceptionHandler的委托模式

为了保持错误响应格式的一致性，我们可以让AuthenticationEntryPoint委托给Spring的HandlerExceptionResolver机制，从而间接触发我们全局@ControllerAdvice中的@ExceptionHandler。这种方法更加优雅，避免了在多个地方重复编写错误响应的序列化逻辑。

首先，我们需要在@ControllerAdvice中定义一个处理AuthenticationException的方法：

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

import java.util.HashMap;
import java.util.Map;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(AuthenticationException.class)
    public ResponseEntity> handleAuthenticationException(AuthenticationException ex) {
        Map errorDetails = new HashMap<>();
        errorDetails.put("timestamp", System.currentTimeMillis());
        errorDetails.put("status", HttpStatus.UNAUTHORIZED.value());
        errorDetails.put("error", "Authentication Error");
        errorDetails.put("message", "Invalid credentials or token: " + ex.getMessage());
        // 可以添加更多自定义字段
        return new ResponseEntity<>(errorDetails, HttpStatus.UNAUTHORIZED);
    }

    // 其他异常处理方法...
}

然后，修改CustomAuthenticationEntryPoint，使其委托给HandlerExceptionResolver：

import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
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 java.io.IOException;

@Component("delegatedAuthenticationEntryPoint") // 指定bean名称，避免与默认的AuthenticationEntryPoint冲突
public class DelegatedAuthentication