Spring Security自定义403和401异常页面的完整解决方案与代码实现

时间：2026-06-18 06:45

针对SpringSecurity默认401和403错误页面不友好的问题，通过自定义AuthenticationEntryPoint和AccessDeniedHandler实现异常处理。根据应用场景，可重定向到自定义页面或返回结构化JSON，提升用户体验。配置中注册自定义处理器即可生效。

引言

在当今Web应用开发领域，安全控制始终是不可忽视的核心议题。Spring Security作为Spring生态中最为成熟且广泛使用的安全框架，为开发者提供了强大的身份认证与访问授权能力。然而，一个现实的问题在于：当用户尝试访问受保护资源时，若未通过认证或权限不足，系统默认会返回HTTP状态码401或403，并附带一个简陋甚至完全空白的错误页面。坦白讲，这种体验既不友好，又显得不够专业，严重影响用户对应用的信赖感。

因此，自定义异常页面成为提升应用安全感知与用户体验的关键环节。本文将深入探讨如何在Spring Security中优雅地处理401和403异常，引导用户跳转到友好的自定义页面。我们将从基础概念出发，逐步构建完整的解决方案，涵盖配置方式、代码实现、最佳实践，并指出若干常见陷阱。

一、理解401与403的区别

动手编写代码之前，有必要先厘清401 Unauthorized与403 Forbidden的语义差异。两者的触发条件和处理逻辑截然不同。

401 Unauthorized（未认证）

含义：用户未提供有效的身份凭证，例如未登录、Token过期、Session失效等。
触发场景：
- 访问需登录的页面但未执行登录操作；
- 提交的JWT Token已过期或签名无效；
- Basic Auth的用户名或密码错误。
HTTP行为：通常附带WWW-Authenticate响应头，提示客户端需要进行身份认证。

403 Forbidden（无权限）

含义：用户已成功认证，身份合法，但不具备访问该资源的权限。
触发场景：
- 普通用户尝试访问管理员专属接口；
- 角色不匹配，例如ROLE_USER的用户访问被@PreAuthorize("hasRole('ADMIN')")保护的方法；
- 权限表达式（SpEL）计算结果为false。
关键点：403出现的前提是用户已通过认证，只是权限不足。

小贴士：混淆401与403是初学者常见的误区。请牢记：401询问“你是谁？”；403则表示“我知道你是谁，但你不能进入。”

SpringSecurity自定义异常页面(403、401)的完整解决方案

二、Spring Security默认的异常处理机制

Spring Security的异常处理机制主要由一系列Filter负责。其中两个核心过滤器承担此项任务：

ExceptionTranslationFilter

位于Filter Chain的中段；
专门捕获AuthenticationException（触发401）和AccessDeniedException（触发403）；
根据异常类型调用对应的处理器。

AuthenticationEntryPoint

处理AuthenticationException，即401场景；
默认实现：Http403ForbiddenEntryPoint（仅返回403，不推荐）或LoginUrlAuthenticationEntryPoint（重定向至登录页）。

AccessDeniedHandler

处理AccessDeniedException，即403场景；
默认实现：AccessDeniedHandlerImpl，直接返回403状态码。

默认情况下，若未进行显式配置，Spring Security将使用内置的简单响应，例如纯文本的“Access Denied”或空白页。在生产环境中，这种做法显然不够理想。

三、自定义401处理：AuthenticationEntryPoint实现

401异常通常发生在用户未登录时尝试访问受保护资源。此时可以考虑将其重定向至登录页，或直接返回JSON格式的错误信息（适用于API场景）。

3.1 Web应用场景：重定向到登录页

对于传统的MVC应用（如Thymeleaf、JSP），最常用的方式是重定向到/login页面。

import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import ja vax.servlet.ServletException;
import ja vax.servlet.http.HttpServletRequest;
import ja vax.servlet.http.HttpServletResponse;
import ja va.io.IOException;

public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    @Override
    public void commence(HttpServletRequest request,
                         HttpServletResponse response,
                         AuthenticationException authException) 
            throws IOException, ServletException {
        
        // 重定向到自定义登录页
        response.sendRedirect("/login?error=unauthenticated");
    }
}

3.2 REST API场景：返回JSON错误

对于前后端分离的架构（如Vue + Spring Boot），应返回结构化的JSON，而非重定向。

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import ja vax.servlet.ServletException;
import ja vax.servlet.http.HttpServletRequest;
import ja vax.servlet.http.HttpServletResponse;
import ja va.io.IOException;
import ja va.util.HashMap;
import ja va.util.Map;

public class RestAuthenticationEntryPoint 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);
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding("UTF-8");

        Map error = new HashMap<>();
        error.put("timestamp", System.currentTimeMillis());
        error.put("status", HttpServletResponse.SC_UNAUTHORIZED);
        error.put("error", "Unauthorized");
        error.put("message", "Authentication is required to access this resource.");
        error.put("path", request.getRequestURI());

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

四、自定义403处理：AccessDeniedHandler实现

403异常表示用户已登录但权限不足。处理方式同样分为Web页面和API两种场景。

4.1 Web应用：跳转到“无权限”页面

创建一个/error/403页面，展示友好的提示信息。

import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.web.access.AccessDeniedHandler;
import ja vax.servlet.ServletException;
import ja vax.servlet.http.HttpServletRequest;
import ja vax.servlet.http.HttpServletResponse;
import ja va.io.IOException;

public class CustomAccessDeniedHandler implements AccessDeniedHandler {

    @Override
    public void handle(HttpServletRequest request,
                       HttpServletResponse response,
                       AccessDeniedException accessDeniedException) 
            throws IOException, ServletException {
        
        // 重定向到自定义403页面
        response.sendRedirect("/error/403");
    }
}

对应的Controller：

@Controller
public class ErrorController {

    @GetMapping("/error/403")
    public String accessDenied() {
        return "error/403"; // 对应templates/error/403.html (Thymeleaf)
    }
}

4.2 REST API：返回JSON格式的403错误

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.MediaType;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.web.access.AccessDeniedHandler;
import ja vax.servlet.ServletException;
import ja vax.servlet.http.HttpServletRequest;
import ja vax.servlet.http.HttpServletResponse;
import ja va.io.IOException;
import ja va.util.HashMap;
import ja va.util.Map;

public class RestAccessDeniedHandler implements AccessDeniedHandler {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void handle(HttpServletRequest request,
                       HttpServletResponse response,
                       AccessDeniedException accessDeniedException) 
            throws IOException, ServletException {
        
        response.setStatus(HttpServletResponse.SC_FORBIDDEN);
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding("UTF-8");

        Map error = new HashMap<>();
        error.put("timestamp", System.currentTimeMillis());
        error.put("status", HttpServletResponse.SC_FORBIDDEN);
        error.put("error", "Forbidden");
        error.put("message", "You do not ha ve permission to access this resource.");
        error.put("path", request.getRequestURI());

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

注意：确保ObjectMapper已正确配置（例如日期格式、空值处理），避免序列化出现问题。

五、在Spring Security配置中注册自定义处理器

完成自定义的AuthenticationEntryPoint与AccessDeniedHandler后，下一步是在SecurityConfig中注册它们。

5.1 Web应用配置示例

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .requestMatchers("/user/**").hasRole("USER")
                .anyRequest().authenticated()
            )
            .formLogin(form -> form
                .loginPage("/login")
                .permitAll()
            )
            .logout(logout -> logout
                .permitAll()
            )
            // 注册自定义401处理器
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint(new CustomAuthenticationEntryPoint())
                .accessDeniedHandler(new CustomAccessDeniedHandler())
            );

        return http.build();
    }

    @Bean
    public UserDetailsService userDetailsService() {
        // 简化示例：内存用户
        UserDetails admin = User.builder()
            .username("admin")
            .password("{noop}password") // 实际应该用加密
            .roles("ADMIN")
            .build();
        UserDetails user = User.builder()
            .username("user")
            .password("{noop}password")
            .roles("USER")
            .build();
        return new InMemoryUserDetailsManager(admin, user);
    }
}

5.2 REST API配置示例

对于无状态的API（如JWT），通常需要禁用Session和Form Login：

@Configuration
@EnableWebSecurity
public class RestSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable()) // 通常API会禁用CSRF
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            // 使用自定义REST异常处理器
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint(new RestAuthenticationEntryPoint())
                .accessDeniedHandler(new RestAccessDeniedHandler())
            )
            .addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    @Bean
    public JwtAuthenticationFilter jwtAuthenticationFilter() {
        return new JwtAuthenticationFilter(); // 自定义JWT过滤器
    }
}

六、全局异常处理 vs Spring Security异常处理

有开发者可能会问：能否直接使用@ControllerAdvice统一处理401/403？

答案是：不能完全替代。

原因在于：

Spring Security抛出的异常（如AccessDeniedException）是在Filter层抛出的，远早于Spring MVC的DispatcherServlet，因此@ControllerAdvice无法捕获。
AuthenticationEntryPoint和AccessDeniedHandler是Spring Security专门设计的扩展点，必须通过Security配置进行注册。

不过，可以在AccessDeniedHandler中调用全局错误服务，实现日志记录、监控告警等功能：

@Service
public class GlobalErrorService {
    public void logAccessDenied(String username, String path) {
        // 记录日志、发送告警等
        System.out.println("Access denied for user: " + username + " on path: " + path);
    }
}

// 在AccessDeniedHandler中注入使用
public class CustomAccessDeniedHandler implements AccessDeniedHandler {

    @Autowired
    private GlobalErrorService errorService;

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                       AccessDeniedException accessDeniedException) 
            throws IOException, ServletException {
        
        String username = SecurityContextHolder.getContext()
            .getAuthentication().getName();
        errorService.logAccessDenied(username, request.getRequestURI());
        
        response.sendRedirect("/error/403");
    }
}

七、进阶：动态选择异常处理器（Web vs API）

在混合应用中，同时存在Web页面和API接口，如何根据请求类型自动切换异常处理器？

方案：基于Content-Type或路径前缀判断

public class DynamicAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final RestAuthenticationEntryPoint restEntryPoint = new RestAuthenticationEntryPoint();
    private final CustomAuthenticationEntryPoint webEntryPoint = new CustomAuthenticationEntryPoint();

    @Override
    public void commence(HttpServletRequest request,
                         HttpServletResponse response,
                         AuthenticationException authException) 
            throws IOException, ServletException {
        
        if (isRestRequest(request)) {
            restEntryPoint.commence(request, response, authException);
        } else {
            webEntryPoint.commence(request, response, authException);
        }
    }

    private boolean isRestRequest(HttpServletRequest request) {
        String uri = request.getRequestURI();
        String accept = request.getHeader("Accept");
        return uri.startsWith("/api/") || 
               (accept != null && accept.contains("application/json"));
    }
}

同理可实现DynamicAccessDeniedHandler。

注意：此方案需要仔细设计判断逻辑，避免误判。

八、测试自定义异常页面

编写若干集成测试，验证配置是否生效。

8.1 测试403场景（Web）

@SpringBootTest
@AutoConfigureTestDatabase
@AutoConfigureMockMvc
class SecurityWebTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @WithMockUser(roles = "USER") // 模拟已登录的普通用户
    void whenAccessAdminPage_thenRedirectTo403() throws Exception {
        mockMvc.perform(get("/admin/dashboard"))
               .andExpect(status().is3xxRedirection())
               .andExpect(redirectedUrl("/error/403"));
    }
}

8.2 测试401场景（API）

@Test
void whenAccessProtectedApiWithoutAuth_thenReturn401Json() throws Exception {
    mockMvc.perform(get("/api/admin/data")
                   .accept(MediaType.APPLICATION_JSON))
           .andExpect(status().isUnauthorized())
           .andExpect(jsonPath("$.error").value("Unauthorized"))
           .andExpect(jsonPath("$.message").exists());
}

使用@WithMockUser可快速模拟不同角色的用户，极大简化安全测试。

九、常见问题与最佳实践

9.1 为什么自定义页面没有生效？

检查顺序：确保.exceptionHandling()配置位于HttpSecurity链的最后部分（虽非强制要求，但逻辑更清晰）。
覆盖问题：不要同时配置formLogin().loginPage()和authenticationEntryPoint()，前者会覆盖后者。
静态资源：确保/error/403页面本身不需要认证，否则会陷入重定向循环。

http.authorizeHttpRequests(authz -> authz
    .requestMatchers("/error/**", "/static/**", "/login").permitAll()
    // ... 其他规则
);

9.2 如何记录异常日志？

在自定义Handler中添加日志：

private static final Logger logger = LoggerFactory.getLogger(CustomAccessDeniedHandler.class);

@Override
public void handle(...) {
    logger.warn("Access denied for IP: {}, Path: {}, User: {}", 
        request.getRemoteAddr(), 
        request.getRequestURI(),
        SecurityContextHolder.getContext().getAuthentication().getName());
    // ...
}

9.3 是否应该暴露详细错误信息？

生产环境：避免在响应中暴露技术细节，如堆栈信息、内部类名；
开发环境：可启用调试信息，便于排查问题。

可通过配置文件控制：

# application-prod.properties
security.error.show-details=false

# application-dev.properties
security.error.show-details=true

在Handler中读取配置：

@Value("${security.error.show-details:false}")
private boolean showDetails;

十、国际化（i18n）支持

为异常页面添加多语言支持，提升用户体验。

10.1 定义消息资源

messages_en.properties:

error.403.title=Access Denied
error.403.message=You don't ha ve permission to view this page.

messages_zh.properties:

error.403.title=访问被拒绝
error.403.message=您没有权限查看此页面。

10.2 在Controller中注入MessageSource

@Controller
public class ErrorController {

    @Autowired
    private MessageSource messageSource;

    @GetMapping("/error/403")
    public String accessDenied(Locale locale, Model model) {
        model.addAttribute("title", messageSource.getMessage("error.403.title", null, locale));
        model.addAttribute("message", messageSource.getMessage("error.403.message", null, locale));
        return "error/403";
    }
}

十一、安全性考量

在设计自定义错误页面时，需要留意几个安全风险：

信息泄露

避免在错误页面上暴露用户ID、内部路径、数据库结构等敏感信息。
例如，不要写成“User 'admin' does not ha ve role ADMIN”，而应写成“Access denied”。

防止钓鱼

错误页面应保持与主站一致的设计风格，防止被仿冒。
使用HTTPS防止中间人篡改错误页面。

速率限制

频繁触发401/403可能预示暴力破解，建议结合RateLimiter（如Redis加Lua）进行限制。

Redis App User Redis App User alt [计数 > 10/分钟] [正常] 请求 /admin (无权限) INCR failed_access:/admin 当前计数返回 429 Too Many Requests 返回 403 页面

十二、总结与展望

通过本文，我们系统地了解了如何在Spring Security中自定义401和403异常页面。回顾关键要点：

✅ 区分401与403：前者表示未认证，后者表示无权限；
✅ 使用正确的扩展点：AuthenticationEntryPoint处理401，AccessDeniedHandler处理403；
✅ 适配不同场景：Web应用使用重定向，API返回JSON；
✅ 增强健壮性：添加日志、国际化、安全防护；
✅ 充分测试：利用@WithMockUser和MockMvc验证行为。

未来，随着微服务和云原生架构的普及，异常处理将更加标准化，例如遵循RFC 7807 Problem Details。Spring Security也在持续演进，比如对Reactive编程模型（WebFlux）的支持，其异常处理机制略有不同，但核心思想一致。

安全不是功能，而是责任。一个友好的错误页面，不仅是用户体验的体现，更是系统安全防线中不可忽视的一环。

希望本文能帮助你在Spring Security的安全之路上走得更稳、更远！

来源：https://www.jb51.net/program/365758686.htm

解决方案

上一篇Spring Security静态资源免认证访问配置方法详解教程 下一篇SpringBoot整合SpringSecurity实现基于URL的接口权限控制详细指南

本站内容用于信息整理与展示，如有侵权或内容问题请及时联系处理。