Spring Security 自定义登出处理器

最后修改:2024年1月8日

by baeldung

1. 概述

Spring Security 框架在认证方面提供了高度灵活且强大的支持。除了用户登录，我们通常还需要处理用户登出事件，有时还需加入一些自定义的登出逻辑。典型场景包括：清除用户缓存、关闭认证会话、记录登出日志等。

为此，Spring Security 提供了 LogoutHandler 接口。本文将带你一步步实现一个自定义的登出处理器，解决实际开发中的“踩坑”需求。

2. 处理登出请求

任何有登录功能的 Web 应用，都必须有登出机制。Spring Security 默认提供了登出处理流程，但如果你需要在用户登出时执行额外操作，就必须介入这个过程。

主要有两种方式可以干预登出行为：

  • ✅ LogoutHandler：用于执行“无副作用”的清理工作（如清缓存），不能抛异常
  • ✅ LogoutSuccessHandler：用于控制登出后的跳转或响应，可抛异常影响流程

2.1. LogoutHandler 接口

LogoutHandler 接口定义如下：

public interface LogoutHandler {
    void logout(HttpServletRequest request, HttpServletResponse response, Authentication authentication);
}

关键点：

  • ✅ 可注册多个 LogoutHandler，Spring Security 会按顺序执行
  • ❌ 实现中严禁抛出异常，否则可能中断登出流程，导致安全上下文未正确清理
  • ⚠️ 适合做“尽力而为”的清理操作，比如缓存失效、会话销毁等

举个例子：你清缓存时数据库连接出问题了，不能因为这个让整个登出失败。所以这类操作要 try-catch 吞掉异常，保证方法平稳退出。

2.2. LogoutSuccessHandler 接口

对比之下，LogoutSuccessHandler 的 onLogoutSuccess 方法可以抛出异常来控制流程：

public interface LogoutSuccessHandler {
    void onLogoutSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) throws IOException, ServletException;
}

特点：

  • ✅ 可用于重定向到登录页、返回 JSON 响应等
  • ❌ 只能注册一个实现，后注册的会覆盖前面的
  • ✅ 是登出流程的“最终裁决者”，适合做响应输出

💡 小结：

  • 清缓存、关资源 → 用 LogoutHandler
  • 控制跳转、返回状态码 → 用 LogoutSuccessHandler

3. LogoutHandler 实战示例

我们来实现一个典型场景：用户登出时，将其从本地缓存中移除，避免后续请求误用旧数据。

3.1. 应用配置

先看 application.properties 中的数据库配置：

spring.datasource.url=jdbc:postgresql://localhost:5432/test_db
spring.datasource.username=dev_user
spring.datasource.password=dev_pass_123
spring.jpa.hibernate.ddl-auto=create

3.2. 用户实体与缓存服务

用户实体 User，对应数据库 users 表：

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(unique = true)
    private String login;

    private String password;

    private String role;

    private String language;

    // standard setters and getters
}

缓存服务 UserCache，使用 ConcurrentHashMap 存用户，避免频繁查库：

@Service
public class UserCache {
    @PersistenceContext
    private EntityManager entityManager;

    private final ConcurrentMap<String, User> store = new ConcurrentHashMap<>(256);

    public User getByUserName(String userName) {
        return store.computeIfAbsent(userName, k -> 
          entityManager.createQuery("from User where login=:login", User.class)
            .setParameter("login", k)
            .getSingleResult());
    }

    public void evictUser(String userName) {
        store.remove(userName);
    }
}

✅ computeIfAbsent 确保只在缓存未命中时查询数据库
✅ evictUser 将在登出时被调用

3.3. 用户接口

提供一个简单接口获取用户语言设置：

@Controller
@RequestMapping(path = "/user")
public class UserController {

    private final UserCache userCache;

    public UserController(UserCache userCache) {
        this.userCache = userCache;
    }

    @GetMapping(path = "/language")
    @ResponseBody
    public String getLanguage() {
        String userName = UserUtils.getAuthenticatedUserName();
        User user = userCache.getByUserName(userName);
        return user.getLanguage();
    }
}

4. 安全配置：注册自定义登出处理器

核心配置在 MvcConfiguration 中完成：

@Configuration
@EnableWebSecurity
public class MvcConfiguration {

    @Autowired
    private DataSource dataSource;

    @Autowired
    private CustomLogoutHandler logoutHandler;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.httpBasic(Customizer.withDefaults())
            .authorizeHttpRequests(authorizationManagerRequestMatcherRegistry ->
                    authorizationManagerRequestMatcherRegistry.requestMatchers(HttpMethod.GET, "/user/**").hasRole("USER"))
            .logout(httpSecurityLogoutConfigurer ->
                    httpSecurityLogoutConfigurer.logoutUrl("/user/logout")
                            .addLogoutHandler(logoutHandler)
                            .logoutSuccessHandler(new HttpStatusReturningLogoutSuccessHandler(HttpStatus.OK)).permitAll())
                .securityContext(httpSecuritySecurityContextConfigurer -> httpSecuritySecurityContextConfigurer.requireExplicitSave(false))
            .csrf(AbstractHttpConfigurer::disable)
            .formLogin(AbstractHttpConfigurer::disable);
        return http.build();
    }
}

关键点解析：

  • ✅ logoutUrl("/user/logout")：自定义登出接口
  • ✅ addLogoutHandler(logoutHandler)：注册我们的自定义处理器
  • ✅ logoutSuccessHandler(...)：登出成功返回 200，适合前后端分离
  • ✅ csrf().disable()：测试环境关闭 CSRF，生产环境请慎用
  • ✅ formLogin().disable()：使用 HTTP Basic，非表单登录

⚠️ 注意：addLogoutHandler 添加的处理器会在登出流程最后阶段执行，确保此时用户仍处于认证状态，可以安全获取 Authentication 信息。

5. 自定义登出处理器实现

CustomLogoutHandler 是本文的核心：

@Service
public class CustomLogoutHandler implements LogoutHandler {

    private final UserCache userCache;

    public CustomLogoutHandler(UserCache userCache) {
        this.userCache = userCache;
    }

    @Override
    public void logout(HttpServletRequest request, HttpServletResponse response, 
      Authentication authentication) {
        String userName = UserUtils.getAuthenticatedUserName();
        userCache.evictUser(userName);
    }
}

简单粗暴，但非常有效：

  • ✅ 通过 UserUtils.getAuthenticatedUserName() 获取当前用户
  • ✅ 调用缓存服务清除该用户
  • ✅ 无异常抛出，符合 LogoutHandler 规范

💡 如果 UserUtils 是你项目中的工具类，确保它能安全获取 SecurityContext 中的用户名，避免 NPE。

6. 集成测试验证

6.1. 验证缓存生效

@Test
public void whenLogin_thenUseUserCache() {
    assertThat(userCache.size()).isZero();

    ResponseEntity<String> response = restTemplate.withBasicAuth("user", "pass")
        .getForEntity(getLanguageUrl(), String.class);

    assertThat(response.getBody()).contains("english");
    assertThat(userCache.size()).isEqualTo(1);

    HttpHeaders requestHeaders = new HttpHeaders();
    requestHeaders.add("Cookie", response.getHeaders()
        .getFirst(HttpHeaders.SET_COOKIE));

    response = restTemplate.exchange(getLanguageUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getBody()).contains("english");

    response = restTemplate.exchange(getLogoutUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getStatusCode().value()).isEqualTo(200);
}

✅ 验证点：

  • 缓存初始为空
  • 登录后缓存命中
  • 再次请求直接走缓存
  • 登出接口可正常调用

6.2. 验证登出清缓存

@Test
public void whenLogout_thenCacheIsEmpty() {
    assertThat(userCache.size()).isZero();

    ResponseEntity<String> response = restTemplate.withBasicAuth("user", "pass")
        .getForEntity(getLanguageUrl(), String.class);

    assertThat(response.getBody()).contains("english");
    assertThat(userCache.size()).isEqualTo(1);

    HttpHeaders requestHeaders = new HttpHeaders();
    requestHeaders.add("Cookie", response.getHeaders()
        .getFirst(HttpHeaders.SET_COOKIE));

    response = restTemplate.exchange(getLogoutUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getStatusCode().value()).isEqualTo(200);

    assertThat(userCache.size()).isZero();

    response = restTemplate.exchange(getLanguageUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getStatusCode().value()).isEqualTo(401);
}

✅ 验证点：

  • 登出后缓存被清空
  • 再次访问受保护接口 → 401 未授权
  • 整个流程闭环，逻辑正确

7. 总结

本文通过一个真实场景，演示了如何使用 Spring Security 的 LogoutHandler 实现自定义登出逻辑。

核心要点回顾：

  • ✅ LogoutHandler 适合做“无异常”的清理工作，可注册多个
  • ✅ LogoutSuccessHandler 用于控制响应，只能有一个
  • ✅ 自定义处理器在登出流程末尾执行，可安全获取用户信息
  • ✅ 清缓存、关会话等操作应放入 LogoutHandler
  • ✅ 生产环境注意异常处理，避免因清理失败影响登出

代码已上传至 GitHub：https://github.com/your-repo/spring-security-custom-logout（示例地址，实际请替换）

原始标题:Spring Security Custom Logout Handler

« 上一篇： 使用 Spring Boot 和 Groovy 构建简易 Web 应用
» 下一篇： Java周报，331