1. 项目概述为什么需要同时支持Form和Token登录在构建现代Web应用特别是微服务架构下的应用时我们常常会面临一个看似矛盾的需求既要为传统的浏览器端用户提供表单登录Form Login的友好体验又要为移动端App、第三方服务或前后端分离架构提供基于Token的无状态API认证。我最近在重构一个老项目的认证模块核心要求就是将Spring Security 3.2.9一个相对经典但功能完整的版本改造为同时支持这两种模式。这不仅仅是加个配置那么简单它涉及到对Spring Security过滤器链的深度理解、认证流程的定制以及如何让两套看似独立的认证机制在同一套安全上下文中和谐共处。简单来说表单登录是给“人”用的用户通过浏览器访问一个登录页面输入用户名密码服务器验证后创建一个Session后续请求通过Session Cookie来维持登录状态。而Token登录通常是JWT或OAuth2 Bearer Token是给“程序”或“客户端”用的客户端在首次认证后获得一个令牌Token后续在请求头中携带这个令牌来访问受保护的API服务器无需维护会话状态。在一个系统中同时提供这两种能力意味着你的应用既能服务于传统的Web门户也能作为API服务器支撑移动端、小程序或第三方集成极大地提升了系统的灵活性和适用范围。2. 核心架构设计与思路拆解2.1 理解Spring Security 3.2.9的认证流程核心Spring Security 3.2.9虽然版本较早但其核心架构——基于过滤器链FilterChain的请求拦截和处理机制——与后续版本一脉相承。要同时支持Form和Token关键在于理解并干预其认证流程。当请求到达时会经过一个由多个Filter组成的链条。对于认证最关键的两个过滤器是UsernamePasswordAuthenticationFilter默认处理/loginPOST请求从表单参数中提取username和password尝试进行认证。成功后会将认证信息Authentication对象存入SecurityContext并通常重定向到默认成功页面。SecurityContextPersistenceFilter位于链条较前位置负责在每个请求开始时从Session中恢复SecurityContext对于Form登录在请求结束时将其保存回Session。我们的目标是在这个链条中插入一个自定义的Token认证过滤器让它能在UsernamePasswordAuthenticationFilter之前运行。这样对于携带Token的API请求我们的自定义过滤器会率先处理并完成认证后续的Form登录过滤器就不会再介入而对于普通的浏览器请求因为没有Token自定义过滤器会放行由后续的Form登录过滤器或Session机制来处理。2.2 方案选型为何选择自定义过滤器而非OAuth2资源服务器在Spring Security的生态中处理Token认证通常有几种方式使用OAuth2ResourceServer在更高版本中、使用JwtAuthenticationFilter等。但在3.2.9版本中对OAuth2和JWT的原生支持相对较弱。更关键的是OAuth2资源服务器的配置通常倾向于只处理Token请求它会默认拒绝没有Token的请求返回401这与我们“同时支持”的目标相悖。因此最直接、最可控的方案是自定义一个AuthenticationFilter并将其集成到Spring Security的过滤器链中。这个过滤器的职责很明确检查请求判断请求头如Authorization: Bearer token或参数中是否携带了预定义的Token。验证Token如果携带了Token则对其进行解析和验证例如验证JWT签名、检查有效期。构建认证对象验证通过后根据Token中的信息如用户名、权限构建一个Authentication对象通常是UsernamePasswordAuthenticationToken。注入安全上下文将这个Authentication对象设置到当前线程的SecurityContextHolder中标志着用户已认证。放行请求过滤器链继续后续的授权逻辑可以正常进行。这个自定义过滤器需要被放置在过滤器链中SecurityContextPersistenceFilter之后但在UsernamePasswordAuthenticationFilter、BasicAuthenticationFilter等默认认证过滤器之前。这样能确保Token认证优先级最高。2.3 配置层面的核心挑战与解决思路在security.xml或Java Config中配置时我们需要解决几个关键问题禁用CSRF对API的影响CSRF跨站请求伪造保护是Form登录场景的重要安全措施但它会要求请求携带CSRF Token这对于使用Token的无状态API来说是多余的甚至会造成阻碍。我们需要配置Spring Security对API路径如/api/**禁用CSRF保护而对Web路径保持启用。会话创建策略对于Form登录我们需要IF_REQUIRED默认或ALWAYS策略来创建和管理Session。对于Token API我们期望是STATELESS策略即不创建和使用Session。这可以通过为不同URL模式配置不同的security:http块并设置各自的create-session属性来实现但更常见的做法是在同一个配置中通过session-management的session-fixation-protection等属性进行全局管理并对API请求在过滤器中显式设置为无状态。认证入口点当未认证用户访问受保护资源时Spring Security需要知道如何响应。对于Web请求通常是重定向到登录页LoginUrlAuthenticationEntryPoint。对于API请求应该返回一个清晰的JSON格式的401错误而不是重定向。这需要我们自定义一个AuthenticationEntryPoint根据请求类型检查Accept头或URL路径来决定响应方式。3. 核心细节解析与实操要点3.1 自定义Token认证过滤器的实现细节下面是一个JwtAuthenticationFilter的核心实现示例。这个过滤器继承自GenericFilterBean以便于在Spring环境中获取配置属性。import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.security.core.userdetails.UserDetailsService; import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; import org.springframework.web.filter.GenericFilterBean; import javax.servlet.FilterChain; import javax.servlet.ServletException; import javax.servlet.ServletRequest; import javax.servlet.ServletResponse; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; public class JwtAuthenticationFilter extends GenericFilterBean { private TokenService tokenService; // 自定义的Token解析、验证服务 private UserDetailsService userDetailsService; // Spring Security的用户详情服务 Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException { HttpServletRequest request (HttpServletRequest) req; HttpServletResponse response (HttpServletResponse) res; // 1. 从请求中提取Token String authHeader request.getHeader(Authorization); String token null; if (authHeader ! null authHeader.startsWith(Bearer )) { token authHeader.substring(7); // 去掉Bearer 前缀 } // 也可以考虑从url参数中获取如 ?tokenxxx但不如Header安全 String username null; if (token ! null) { try { // 2. 验证并解析Token username tokenService.validateAndGetUsernameFromToken(token); } catch (Exception e) { // Token无效或过期记录日志但不抛出异常继续过滤器链 // 后续的认证过滤器如表单登录会处理 logger.debug(Invalid JWT token: e.getMessage()); } } // 3. 如果Token有效且当前上下文没有认证信息则构建认证对象 if (username ! null SecurityContextHolder.getContext().getAuthentication() null) { // 从数据库或缓存中加载用户详情权限信息 UserDetails userDetails this.userDetailsService.loadUserByUsername(username); // 创建已认证的Token UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities()); authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request)); // 4. 注入安全上下文 SecurityContextHolder.getContext().setAuthentication(authentication); // 5. 可选对于无状态API显式告知Security不要创建Session // request.setAttribute(__spring_security_session_mgmt_filter_applied, Boolean.TRUE); } // 6. 继续过滤器链 chain.doFilter(request, response); } // Setter方法用于依赖注入 public void setTokenService(TokenService tokenService) { this.tokenService tokenService; } public void setUserDetailsService(UserDetailsService userDetailsService) { this.userDetailsService userDetailsService; } }关键点解析Bearer前缀这是OAuth2规范中推荐的Token携带方式已成为业界标准。过滤器需要识别并剥离这个前缀。异常处理在Token解析失败时我们选择静默失败记录debug日志而不是直接抛出异常或返回401。这是因为这个过滤器需要与Form登录共存。一个没有Token或Token无效的请求很可能是一个普通的Web请求应该留给后面的UsernamePasswordAuthenticationFilter或Session机制去处理。如果在此处直接中断会破坏Form登录流程。UserDetailsService即使使用JWT通常也需要从数据库或缓存中加载用户的最新权限信息。JWT里可以存储用户名和基础权限但若权限模型复杂或可能动态变更从持久化存储加载是更可靠的做法。这里体现了Token认证与后端用户体系的关联。无状态Session注释掉的第5步展示了如何暗示Spring Security的SessionManagementFilter不要为这次请求创建Session。更正式的做法是在security.xml中为API路径配置单独的http块并设置create-sessionstateless。3.2 安全配置security.xml的关键整合如何在XML配置中将这个自定义过滤器插入到正确的位置是成功的关键。以下是一个简化的配置示例beans:beans xmlnshttp://www.springframework.org/schema/security xmlns:beanshttp://www.springframework.org/schema/beans xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security.xsd !-- 定义自定义过滤器和相关Bean -- beans:bean idtokenService classcom.yourcompany.security.JwtTokenService/ beans:bean idjwtAuthenticationFilter classcom.yourcompany.security.JwtAuthenticationFilter beans:property nametokenService reftokenService/ beans:property nameuserDetailsService refuserDetailsService/ /beans:bean http pattern/api/** use-expressionstrue !-- 为API路径配置自定义过滤器链 -- custom-filter refjwtAuthenticationFilter beforeFORM_LOGIN_FILTER/ !-- 关键在FORM_LOGIN_FILTER之前插入 -- intercept-url pattern/api/** accessisAuthenticated() / !-- API都需要认证 -- csrf disabledtrue/ !-- API禁用CSRF -- session-management session-fixation-protectionnone/ !-- 可设置为无状态 -- http-basic entry-point-refrestAuthenticationEntryPoint/ !-- 自定义的API认证入口点返回JSON 401 -- /http http use-expressionstrue !-- 默认的Web路径配置 -- intercept-url pattern/login* accesspermitAll / intercept-url pattern/** accessisAuthenticated() / form-login login-page/login.html default-target-url/home authentication-failure-url/login.html?errortrue login-processing-url/perform_login/ logout logout-url/perform_logout delete-cookiesJSESSIONID / csrf/ !-- Web端启用CSRF -- !-- 注意这里没有引用jwt过滤器Web请求走默认流程 -- /http authentication-manager authentication-provider user-service-refuserDetailsService password-encoder refpasswordEncoder/ /authentication-provider /authentication-manager !-- 定义自定义的认证入口点Bean -- beans:bean idrestAuthenticationEntryPoint classcom.yourcompany.security.RestAuthenticationEntryPoint/ /beans:beans配置要点解析两个http元素这是实现URL模式差异化配置的核心。第一个http的pattern/api/**匹配所有API请求第二个没有pattern的作为默认配置匹配其他所有请求Web请求。custom-filter的before属性FORM_LOGIN_FILTER是Spring Security定义的一个过滤器位置常量代表UsernamePasswordAuthenticationFilter。将我们的jwtAuthenticationFilter放在它之前确保了Token认证的优先性。差异化的CSRF和Session策略在API配置中明确禁用CSRF并配置无状态Session而在Web配置中启用它们。这是实现“同时支持”的关键安全策略分离。自定义AuthenticationEntryPointrestAuthenticationEntryPoint这个Bean需要实现AuthenticationEntryPoint接口在其commence方法中设置响应状态码为401内容类型为application/json并写入一个JSON格式的错误信息。这样未认证的API访问会得到友好的JSON提示而不是跳转到HTML登录页。3.3 Token的生成与验证服务TokenService自定义过滤器依赖的TokenService是Token体系的核心。它负责生成在登录成功后和验证Token。import io.jsonwebtoken.Claims; import io.jsonwebtoken.Jwts; import io.jsonwebtoken.SignatureAlgorithm; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import java.util.Date; Component public class JwtTokenService { Value(${jwt.secret}) private String secret; // 签名密钥务必保密且足够复杂 Value(${jwt.expiration}) private Long expiration; // 过期时间如3600000 (1小时) /** * 根据用户名生成Token */ public String generateToken(String username) { Date now new Date(); Date expiryDate new Date(now.getTime() expiration); return Jwts.builder() .setSubject(username) // 主题通常放用户名 .setIssuedAt(now) // 签发时间 .setExpiration(expiryDate) // 过期时间 .signWith(SignatureAlgorithm.HS512, secret) // 签名算法和密钥 .compact(); } /** * 从Token中解析用户名 */ public String getUsernameFromToken(String token) { Claims claims Jwts.parser() .setSigningKey(secret) .parseClaimsJws(token) .getBody(); return claims.getSubject(); } /** * 验证Token是否有效 */ public boolean validateToken(String token) { try { Jwts.parser().setSigningKey(secret).parseClaimsJws(token); return true; } catch (Exception e) { // 签名无效、Token过期、格式错误等 return false; } } // 一个合并了验证和获取用户名的方法供过滤器使用 public String validateAndGetUsernameFromToken(String token) throws Exception { if (!validateToken(token)) { throw new Exception(Invalid or expired JWT token); } return getUsernameFromToken(token); } }注意事项密钥安全jwt.secret是签名的核心必须足够复杂建议使用256位以上的随机字符串并且绝不能提交到版本库。应通过环境变量或配置服务器注入。Token存储生成Token后在Form登录成功的处理器或专门的API登录接口中需要将Token返回给客户端。服务器端不应存储已签发的JWT这是JWT无状态的优势。但可以考虑将Token加入黑名单如登出时以实现即时失效这需要引入Redis等缓存。信息载荷除了用户名subject你还可以在JWT的claims中加入用户ID、角色等必要信息减少验证时查询数据库的次数。但注意不要放入敏感信息因为JWT的Payload是Base64编码可以被解码查看。4. 实操过程与核心环节实现4.1 构建支持双模式登录的认证端点我们需要一个统一的“登录”入口它能根据客户端的不同返回不同的结果。对于Web表单提交Spring Security的UsernamePasswordAuthenticationFilter默认处理/loginPOST。对于API登录我们需要额外提供一个端点比如/api/auth/login。1. 自定义API登录控制器RestController RequestMapping(/api/auth) public class AuthController { Autowired private AuthenticationManager authenticationManager; Autowired private JwtTokenService tokenService; Autowired private UserDetailsService userDetailsService; PostMapping(/login) public ResponseEntity? createAuthenticationToken(RequestBody LoginRequest loginRequest) { // 1. 执行认证 Authentication authentication authenticationManager.authenticate( new UsernamePasswordAuthenticationToken( loginRequest.getUsername(), loginRequest.getPassword() ) ); SecurityContextHolder.getContext().setAuthentication(authentication); // 2. 加载用户详情获取权限可选JWT中也可包含 final UserDetails userDetails userDetailsService.loadUserByUsername(loginRequest.getUsername()); // 3. 生成JWT Token final String token tokenService.generateToken(userDetails.getUsername()); // 4. 返回Token和用户基本信息 return ResponseEntity.ok(new JwtResponse(token, userDetails.getUsername(), userDetails.getAuthorities())); } // 简单的请求响应对象 public static class LoginRequest { private String username; private String password; // getters and setters } public static class JwtResponse { private final String token; private final String username; private final Collection? extends GrantedAuthority authorities; // constructor and getters } }这个控制器手动调用了AuthenticationManager进行认证与Form登录的后台逻辑一致。认证成功后生成JWT Token并返回给客户端如移动端。2. 配置Security使API登录端点可匿名访问在security.xml的API配置块中需要确保/api/auth/login路径允许未认证访问。http pattern/api/** use-expressionstrue intercept-url pattern/api/auth/login accesspermitAll / intercept-url pattern/api/** accessisAuthenticated() / !-- ... other config ... -- /http4.2 整合Form登录与Token生成的钩子如果我们希望在用户通过传统的Web表单登录后也能为其生成一个Token例如用于后续的AJAX调用或移动端同步我们可以定制一个AuthenticationSuccessHandler。Component(customAuthenticationSuccessHandler) public class CustomAuthenticationSuccessHandler extends SavedRequestAwareAuthenticationSuccessHandler { Autowired private JwtTokenService tokenService; Override public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) throws IOException, ServletException { // 1. 调用父类方法保持默认的重定向等行为 super.onAuthenticationSuccess(request, response, authentication); // 2. 生成Token String username authentication.getName(); String token tokenService.generateToken(username); // 3. 可以将Token放到Session、Cookie或者响应头中供前端使用 // 例如放到响应头中注意前端JavaScript需要能读取 response.setHeader(X-Auth-Token, token); // 或者如果登录请求是AJAX可以返回JSON if (XMLHttpRequest.equals(request.getHeader(X-Requested-With))) { response.setContentType(application/json); response.getWriter().write({\token\: \ token \}); return; // 避免重定向 } } }然后在security.xml的Form登录配置中引用这个处理器form-login login-page/login.html authentication-success-handler-refcustomAuthenticationSuccessHandler ... /这样无论是通过表单还是API登录用户都能获得一个Token实现了认证状态的“双轨制”同步。4.3 权限系统的统一处理无论是通过Session认证的用户还是通过Token认证的用户最终在SecurityContextHolder中都会持有一个Authentication对象。Spring Security的授权机制如PreAuthorize,hasRole()是基于这个对象中的GrantedAuthority集合进行判断的。因此只要我们在UserDetailsService中正确加载了用户的权限信息并设置到Authentication对象中自定义过滤器和登录控制器中都做了这一步那么后续的权限检查对两种认证方式是完全透明的无需额外处理。5. 常见问题与排查技巧实录在实际整合过程中我踩过不少坑这里总结几个典型问题和解决方案。5.1 问题Token认证成功后访问API仍返回401或重定向到登录页排查思路检查过滤器顺序这是最常见的原因。确保你的JwtAuthenticationFilter被正确添加到了http pattern/api/**的配置中并且位置在beforeFORM_LOGIN_FILTER。你可以通过开启Spring Security的Debug日志来查看过滤器链。检查CSRF配置确认在API的http配置中设置了csrf disabledtrue/。如果CSRF被启用POST/PUT/DELETE等非GET请求会被要求携带CSRF Token而你的API请求很可能没有。检查Session策略冲突如果API请求意外地创建了Session可能会干扰无状态认证。确保API配置中session-management session-fixation-protectionnone/或者在自定义过滤器中尝试阻止Session创建如前文代码注释所示。验证Token本身在过滤器中打印日志确认Token被正确提取、解析并且username不为空。检查TokenService的签名密钥和过期时间配置。5.2 问题Form登录和Token登录的用户权限不同步场景用户通过表单登录后在后台修改了角色权限但该用户之前获取的Token在有效期内依然持有旧的权限。解决方案缩短Token有效期这是最简单的方法降低权限不一致的窗口期。结合使用Refresh Token机制在Access Token过期后用Refresh Token获取新的Access Token此时会重新加载用户权限。在Token中嵌入版本号或时间戳在用户权限变更时更新一个存储在用户记录中的“权限版本号”或“最后修改时间”。将这个信息也编码到JWT的Claims中。在自定义过滤器验证Token时不仅验证签名和过期时间还要从数据库取出当前用户的“权限版本号”与Token中的进行比对如果不一致则判定Token失效。使用黑名单/白名单在用户登出或权限变更时将旧的Token ID加入Redis黑名单。在自定义过滤器验证Token时增加一步黑名单检查。这增加了状态管理但提供了最精细的控制。5.3 问题如何优雅地处理“登录失败”Form登录失败Spring Security默认会重定向到authentication-failure-url。你可以配置一个自定义的AuthenticationFailureHandler根据错误类型如密码错误、用户锁定返回不同的提示信息或者记录登录失败次数用于防暴力破解。API Token登录失败在你的/api/auth/login端点中authenticationManager.authenticate()调用会抛出AuthenticationException如BadCredentialsException。你需要用ExceptionHandler或全局异常处理器捕获它并返回结构化的JSON错误响应例如{ status: 401, error: Unauthorized, message: 用户名或密码错误, path: /api/auth/login }绝对不要在错误信息中透露是用户名不存在还是密码错误这属于安全信息泄露。统一返回“认证失败”即可。5.4 性能与安全考量Token验证的性能JWT的签名验证是计算密集型操作。对于每个API请求都进行完整的JWT解析和签名验证可能会成为性能瓶颈。可以考虑在验证通过后将解析出的用户信息如username缓存在一个线程安全的缓存如ConcurrentHashMap中Key为Token本身或Token的哈希值并设置一个较短的缓存时间如5分钟。这样在Token有效期内同一Token的重复请求可以快速通过缓存验证。密钥轮换出于安全考虑JWT签名密钥应定期更换。在轮换期间新旧密钥需要同时支持一段时间。可以在TokenService中维护一个密钥列表验证时依次尝试。生成新Token时只使用最新密钥。防止Token泄露务必使用HTTPS来传输Token。避免将Token存储在容易被XSS攻击获取的地方如LocalStorage可以考虑使用HttpOnly的Cookie但这会与纯API客户端的用法产生矛盾需要权衡。对于敏感操作应要求二次认证。整合Spring Security 3.2.9同时支持Form和Token登录是一个深入理解Spring Security工作机制的绝佳实践。它要求你打破“非此即彼”的思维从请求的生命周期和过滤器链的层面去设计认证流程。核心在于优先级控制和差异化配置让Token过滤器以高优先级处理API请求并阻止后续的Session相关流程同时为Web请求保留完整的Form登录和Session管理流程。这种架构不仅满足了多样化的客户端需求也为系统从传统单体应用向现代化微服务架构平滑演进奠定了基础。
Spring Security 3.2.9 同时支持表单登录与Token认证的架构设计与实现
发布时间：2026/6/16 9:00:05
1. 项目概述为什么需要同时支持Form和Token登录在构建现代Web应用特别是微服务架构下的应用时我们常常会面临一个看似矛盾的需求既要为传统的浏览器端用户提供表单登录Form Login的友好体验又要为移动端App、第三方服务或前后端分离架构提供基于Token的无状态API认证。我最近在重构一个老项目的认证模块核心要求就是将Spring Security 3.2.9一个相对经典但功能完整的版本改造为同时支持这两种模式。这不仅仅是加个配置那么简单它涉及到对Spring Security过滤器链的深度理解、认证流程的定制以及如何让两套看似独立的认证机制在同一套安全上下文中和谐共处。简单来说表单登录是给“人”用的用户通过浏览器访问一个登录页面输入用户名密码服务器验证后创建一个Session后续请求通过Session Cookie来维持登录状态。而Token登录通常是JWT或OAuth2 Bearer Token是给“程序”或“客户端”用的客户端在首次认证后获得一个令牌Token后续在请求头中携带这个令牌来访问受保护的API服务器无需维护会话状态。在一个系统中同时提供这两种能力意味着你的应用既能服务于传统的Web门户也能作为API服务器支撑移动端、小程序或第三方集成极大地提升了系统的灵活性和适用范围。2. 核心架构设计与思路拆解2.1 理解Spring Security 3.2.9的认证流程核心Spring Security 3.2.9虽然版本较早但其核心架构——基于过滤器链FilterChain的请求拦截和处理机制——与后续版本一脉相承。要同时支持Form和Token关键在于理解并干预其认证流程。当请求到达时会经过一个由多个Filter组成的链条。对于认证最关键的两个过滤器是UsernamePasswordAuthenticationFilter默认处理/loginPOST请求从表单参数中提取username和password尝试进行认证。成功后会将认证信息Authentication对象存入SecurityContext并通常重定向到默认成功页面。SecurityContextPersistenceFilter位于链条较前位置负责在每个请求开始时从Session中恢复SecurityContext对于Form登录在请求结束时将其保存回Session。我们的目标是在这个链条中插入一个自定义的Token认证过滤器让它能在UsernamePasswordAuthenticationFilter之前运行。这样对于携带Token的API请求我们的自定义过滤器会率先处理并完成认证后续的Form登录过滤器就不会再介入而对于普通的浏览器请求因为没有Token自定义过滤器会放行由后续的Form登录过滤器或Session机制来处理。2.2 方案选型为何选择自定义过滤器而非OAuth2资源服务器在Spring Security的生态中处理Token认证通常有几种方式使用OAuth2ResourceServer在更高版本中、使用JwtAuthenticationFilter等。但在3.2.9版本中对OAuth2和JWT的原生支持相对较弱。更关键的是OAuth2资源服务器的配置通常倾向于只处理Token请求它会默认拒绝没有Token的请求返回401这与我们“同时支持”的目标相悖。因此最直接、最可控的方案是自定义一个AuthenticationFilter并将其集成到Spring Security的过滤器链中。这个过滤器的职责很明确检查请求判断请求头如Authorization: Bearer token或参数中是否携带了预定义的Token。验证Token如果携带了Token则对其进行解析和验证例如验证JWT签名、检查有效期。构建认证对象验证通过后根据Token中的信息如用户名、权限构建一个Authentication对象通常是UsernamePasswordAuthenticationToken。注入安全上下文将这个Authentication对象设置到当前线程的SecurityContextHolder中标志着用户已认证。放行请求过滤器链继续后续的授权逻辑可以正常进行。这个自定义过滤器需要被放置在过滤器链中SecurityContextPersistenceFilter之后但在UsernamePasswordAuthenticationFilter、BasicAuthenticationFilter等默认认证过滤器之前。这样能确保Token认证优先级最高。2.3 配置层面的核心挑战与解决思路在security.xml或Java Config中配置时我们需要解决几个关键问题禁用CSRF对API的影响CSRF跨站请求伪造保护是Form登录场景的重要安全措施但它会要求请求携带CSRF Token这对于使用Token的无状态API来说是多余的甚至会造成阻碍。我们需要配置Spring Security对API路径如/api/**禁用CSRF保护而对Web路径保持启用。会话创建策略对于Form登录我们需要IF_REQUIRED默认或ALWAYS策略来创建和管理Session。对于Token API我们期望是STATELESS策略即不创建和使用Session。这可以通过为不同URL模式配置不同的security:http块并设置各自的create-session属性来实现但更常见的做法是在同一个配置中通过session-management的session-fixation-protection等属性进行全局管理并对API请求在过滤器中显式设置为无状态。认证入口点当未认证用户访问受保护资源时Spring Security需要知道如何响应。对于Web请求通常是重定向到登录页LoginUrlAuthenticationEntryPoint。对于API请求应该返回一个清晰的JSON格式的401错误而不是重定向。这需要我们自定义一个AuthenticationEntryPoint根据请求类型检查Accept头或URL路径来决定响应方式。3. 核心细节解析与实操要点3.1 自定义Token认证过滤器的实现细节下面是一个JwtAuthenticationFilter的核心实现示例。这个过滤器继承自GenericFilterBean以便于在Spring环境中获取配置属性。import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.security.core.userdetails.UserDetailsService; import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; import org.springframework.web.filter.GenericFilterBean; import javax.servlet.FilterChain; import javax.servlet.ServletException; import javax.servlet.ServletRequest; import javax.servlet.ServletResponse; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; public class JwtAuthenticationFilter extends GenericFilterBean { private TokenService tokenService; // 自定义的Token解析、验证服务 private UserDetailsService userDetailsService; // Spring Security的用户详情服务 Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException { HttpServletRequest request (HttpServletRequest) req; HttpServletResponse response (HttpServletResponse) res; // 1. 从请求中提取Token String authHeader request.getHeader(Authorization); String token null; if (authHeader ! null authHeader.startsWith(Bearer )) { token authHeader.substring(7); // 去掉Bearer 前缀 } // 也可以考虑从url参数中获取如 ?tokenxxx但不如Header安全 String username null; if (token ! null) { try { // 2. 验证并解析Token username tokenService.validateAndGetUsernameFromToken(token); } catch (Exception e) { // Token无效或过期记录日志但不抛出异常继续过滤器链 // 后续的认证过滤器如表单登录会处理 logger.debug(Invalid JWT token: e.getMessage()); } } // 3. 如果Token有效且当前上下文没有认证信息则构建认证对象 if (username ! null SecurityContextHolder.getContext().getAuthentication() null) { // 从数据库或缓存中加载用户详情权限信息 UserDetails userDetails this.userDetailsService.loadUserByUsername(username); // 创建已认证的Token UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities()); authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request)); // 4. 注入安全上下文 SecurityContextHolder.getContext().setAuthentication(authentication); // 5. 可选对于无状态API显式告知Security不要创建Session // request.setAttribute(__spring_security_session_mgmt_filter_applied, Boolean.TRUE); } // 6. 继续过滤器链 chain.doFilter(request, response); } // Setter方法用于依赖注入 public void setTokenService(TokenService tokenService) { this.tokenService tokenService; } public void setUserDetailsService(UserDetailsService userDetailsService) { this.userDetailsService userDetailsService; } }关键点解析Bearer前缀这是OAuth2规范中推荐的Token携带方式已成为业界标准。过滤器需要识别并剥离这个前缀。异常处理在Token解析失败时我们选择静默失败记录debug日志而不是直接抛出异常或返回401。这是因为这个过滤器需要与Form登录共存。一个没有Token或Token无效的请求很可能是一个普通的Web请求应该留给后面的UsernamePasswordAuthenticationFilter或Session机制去处理。如果在此处直接中断会破坏Form登录流程。UserDetailsService即使使用JWT通常也需要从数据库或缓存中加载用户的最新权限信息。JWT里可以存储用户名和基础权限但若权限模型复杂或可能动态变更从持久化存储加载是更可靠的做法。这里体现了Token认证与后端用户体系的关联。无状态Session注释掉的第5步展示了如何暗示Spring Security的SessionManagementFilter不要为这次请求创建Session。更正式的做法是在security.xml中为API路径配置单独的http块并设置create-sessionstateless。3.2 安全配置security.xml的关键整合如何在XML配置中将这个自定义过滤器插入到正确的位置是成功的关键。以下是一个简化的配置示例beans:beans xmlnshttp://www.springframework.org/schema/security xmlns:beanshttp://www.springframework.org/schema/beans xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security.xsd !-- 定义自定义过滤器和相关Bean -- beans:bean idtokenService classcom.yourcompany.security.JwtTokenService/ beans:bean idjwtAuthenticationFilter classcom.yourcompany.security.JwtAuthenticationFilter beans:property nametokenService reftokenService/ beans:property nameuserDetailsService refuserDetailsService/ /beans:bean http pattern/api/** use-expressionstrue !-- 为API路径配置自定义过滤器链 -- custom-filter refjwtAuthenticationFilter beforeFORM_LOGIN_FILTER/ !-- 关键在FORM_LOGIN_FILTER之前插入 -- intercept-url pattern/api/** accessisAuthenticated() / !-- API都需要认证 -- csrf disabledtrue/ !-- API禁用CSRF -- session-management session-fixation-protectionnone/ !-- 可设置为无状态 -- http-basic entry-point-refrestAuthenticationEntryPoint/ !-- 自定义的API认证入口点返回JSON 401 -- /http http use-expressionstrue !-- 默认的Web路径配置 -- intercept-url pattern/login* accesspermitAll / intercept-url pattern/** accessisAuthenticated() / form-login login-page/login.html default-target-url/home authentication-failure-url/login.html?errortrue login-processing-url/perform_login/ logout logout-url/perform_logout delete-cookiesJSESSIONID / csrf/ !-- Web端启用CSRF -- !-- 注意这里没有引用jwt过滤器Web请求走默认流程 -- /http authentication-manager authentication-provider user-service-refuserDetailsService password-encoder refpasswordEncoder/ /authentication-provider /authentication-manager !-- 定义自定义的认证入口点Bean -- beans:bean idrestAuthenticationEntryPoint classcom.yourcompany.security.RestAuthenticationEntryPoint/ /beans:beans配置要点解析两个http元素这是实现URL模式差异化配置的核心。第一个http的pattern/api/**匹配所有API请求第二个没有pattern的作为默认配置匹配其他所有请求Web请求。custom-filter的before属性FORM_LOGIN_FILTER是Spring Security定义的一个过滤器位置常量代表UsernamePasswordAuthenticationFilter。将我们的jwtAuthenticationFilter放在它之前确保了Token认证的优先性。差异化的CSRF和Session策略在API配置中明确禁用CSRF并配置无状态Session而在Web配置中启用它们。这是实现“同时支持”的关键安全策略分离。自定义AuthenticationEntryPointrestAuthenticationEntryPoint这个Bean需要实现AuthenticationEntryPoint接口在其commence方法中设置响应状态码为401内容类型为application/json并写入一个JSON格式的错误信息。这样未认证的API访问会得到友好的JSON提示而不是跳转到HTML登录页。3.3 Token的生成与验证服务TokenService自定义过滤器依赖的TokenService是Token体系的核心。它负责生成在登录成功后和验证Token。import io.jsonwebtoken.Claims; import io.jsonwebtoken.Jwts; import io.jsonwebtoken.SignatureAlgorithm; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import java.util.Date; Component public class JwtTokenService { Value(${jwt.secret}) private String secret; // 签名密钥务必保密且足够复杂 Value(${jwt.expiration}) private Long expiration; // 过期时间如3600000 (1小时) /** * 根据用户名生成Token */ public String generateToken(String username) { Date now new Date(); Date expiryDate new Date(now.getTime() expiration); return Jwts.builder() .setSubject(username) // 主题通常放用户名 .setIssuedAt(now) // 签发时间 .setExpiration(expiryDate) // 过期时间 .signWith(SignatureAlgorithm.HS512, secret) // 签名算法和密钥 .compact(); } /** * 从Token中解析用户名 */ public String getUsernameFromToken(String token) { Claims claims Jwts.parser() .setSigningKey(secret) .parseClaimsJws(token) .getBody(); return claims.getSubject(); } /** * 验证Token是否有效 */ public boolean validateToken(String token) { try { Jwts.parser().setSigningKey(secret).parseClaimsJws(token); return true; } catch (Exception e) { // 签名无效、Token过期、格式错误等 return false; } } // 一个合并了验证和获取用户名的方法供过滤器使用 public String validateAndGetUsernameFromToken(String token) throws Exception { if (!validateToken(token)) { throw new Exception(Invalid or expired JWT token); } return getUsernameFromToken(token); } }注意事项密钥安全jwt.secret是签名的核心必须足够复杂建议使用256位以上的随机字符串并且绝不能提交到版本库。应通过环境变量或配置服务器注入。Token存储生成Token后在Form登录成功的处理器或专门的API登录接口中需要将Token返回给客户端。服务器端不应存储已签发的JWT这是JWT无状态的优势。但可以考虑将Token加入黑名单如登出时以实现即时失效这需要引入Redis等缓存。信息载荷除了用户名subject你还可以在JWT的claims中加入用户ID、角色等必要信息减少验证时查询数据库的次数。但注意不要放入敏感信息因为JWT的Payload是Base64编码可以被解码查看。4. 实操过程与核心环节实现4.1 构建支持双模式登录的认证端点我们需要一个统一的“登录”入口它能根据客户端的不同返回不同的结果。对于Web表单提交Spring Security的UsernamePasswordAuthenticationFilter默认处理/loginPOST。对于API登录我们需要额外提供一个端点比如/api/auth/login。1. 自定义API登录控制器RestController RequestMapping(/api/auth) public class AuthController { Autowired private AuthenticationManager authenticationManager; Autowired private JwtTokenService tokenService; Autowired private UserDetailsService userDetailsService; PostMapping(/login) public ResponseEntity? createAuthenticationToken(RequestBody LoginRequest loginRequest) { // 1. 执行认证 Authentication authentication authenticationManager.authenticate( new UsernamePasswordAuthenticationToken( loginRequest.getUsername(), loginRequest.getPassword() ) ); SecurityContextHolder.getContext().setAuthentication(authentication); // 2. 加载用户详情获取权限可选JWT中也可包含 final UserDetails userDetails userDetailsService.loadUserByUsername(loginRequest.getUsername()); // 3. 生成JWT Token final String token tokenService.generateToken(userDetails.getUsername()); // 4. 返回Token和用户基本信息 return ResponseEntity.ok(new JwtResponse(token, userDetails.getUsername(), userDetails.getAuthorities())); } // 简单的请求响应对象 public static class LoginRequest { private String username; private String password; // getters and setters } public static class JwtResponse { private final String token; private final String username; private final Collection? extends GrantedAuthority authorities; // constructor and getters } }这个控制器手动调用了AuthenticationManager进行认证与Form登录的后台逻辑一致。认证成功后生成JWT Token并返回给客户端如移动端。2. 配置Security使API登录端点可匿名访问在security.xml的API配置块中需要确保/api/auth/login路径允许未认证访问。http pattern/api/** use-expressionstrue intercept-url pattern/api/auth/login accesspermitAll / intercept-url pattern/api/** accessisAuthenticated() / !-- ... other config ... -- /http4.2 整合Form登录与Token生成的钩子如果我们希望在用户通过传统的Web表单登录后也能为其生成一个Token例如用于后续的AJAX调用或移动端同步我们可以定制一个AuthenticationSuccessHandler。Component(customAuthenticationSuccessHandler) public class CustomAuthenticationSuccessHandler extends SavedRequestAwareAuthenticationSuccessHandler { Autowired private JwtTokenService tokenService; Override public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) throws IOException, ServletException { // 1. 调用父类方法保持默认的重定向等行为 super.onAuthenticationSuccess(request, response, authentication); // 2. 生成Token String username authentication.getName(); String token tokenService.generateToken(username); // 3. 可以将Token放到Session、Cookie或者响应头中供前端使用 // 例如放到响应头中注意前端JavaScript需要能读取 response.setHeader(X-Auth-Token, token); // 或者如果登录请求是AJAX可以返回JSON if (XMLHttpRequest.equals(request.getHeader(X-Requested-With))) { response.setContentType(application/json); response.getWriter().write({\token\: \ token \}); return; // 避免重定向 } } }然后在security.xml的Form登录配置中引用这个处理器form-login login-page/login.html authentication-success-handler-refcustomAuthenticationSuccessHandler ... /这样无论是通过表单还是API登录用户都能获得一个Token实现了认证状态的“双轨制”同步。4.3 权限系统的统一处理无论是通过Session认证的用户还是通过Token认证的用户最终在SecurityContextHolder中都会持有一个Authentication对象。Spring Security的授权机制如PreAuthorize,hasRole()是基于这个对象中的GrantedAuthority集合进行判断的。因此只要我们在UserDetailsService中正确加载了用户的权限信息并设置到Authentication对象中自定义过滤器和登录控制器中都做了这一步那么后续的权限检查对两种认证方式是完全透明的无需额外处理。5. 常见问题与排查技巧实录在实际整合过程中我踩过不少坑这里总结几个典型问题和解决方案。5.1 问题Token认证成功后访问API仍返回401或重定向到登录页排查思路检查过滤器顺序这是最常见的原因。确保你的JwtAuthenticationFilter被正确添加到了http pattern/api/**的配置中并且位置在beforeFORM_LOGIN_FILTER。你可以通过开启Spring Security的Debug日志来查看过滤器链。检查CSRF配置确认在API的http配置中设置了csrf disabledtrue/。如果CSRF被启用POST/PUT/DELETE等非GET请求会被要求携带CSRF Token而你的API请求很可能没有。检查Session策略冲突如果API请求意外地创建了Session可能会干扰无状态认证。确保API配置中session-management session-fixation-protectionnone/或者在自定义过滤器中尝试阻止Session创建如前文代码注释所示。验证Token本身在过滤器中打印日志确认Token被正确提取、解析并且username不为空。检查TokenService的签名密钥和过期时间配置。5.2 问题Form登录和Token登录的用户权限不同步场景用户通过表单登录后在后台修改了角色权限但该用户之前获取的Token在有效期内依然持有旧的权限。解决方案缩短Token有效期这是最简单的方法降低权限不一致的窗口期。结合使用Refresh Token机制在Access Token过期后用Refresh Token获取新的Access Token此时会重新加载用户权限。在Token中嵌入版本号或时间戳在用户权限变更时更新一个存储在用户记录中的“权限版本号”或“最后修改时间”。将这个信息也编码到JWT的Claims中。在自定义过滤器验证Token时不仅验证签名和过期时间还要从数据库取出当前用户的“权限版本号”与Token中的进行比对如果不一致则判定Token失效。使用黑名单/白名单在用户登出或权限变更时将旧的Token ID加入Redis黑名单。在自定义过滤器验证Token时增加一步黑名单检查。这增加了状态管理但提供了最精细的控制。5.3 问题如何优雅地处理“登录失败”Form登录失败Spring Security默认会重定向到authentication-failure-url。你可以配置一个自定义的AuthenticationFailureHandler根据错误类型如密码错误、用户锁定返回不同的提示信息或者记录登录失败次数用于防暴力破解。API Token登录失败在你的/api/auth/login端点中authenticationManager.authenticate()调用会抛出AuthenticationException如BadCredentialsException。你需要用ExceptionHandler或全局异常处理器捕获它并返回结构化的JSON错误响应例如{ status: 401, error: Unauthorized, message: 用户名或密码错误, path: /api/auth/login }绝对不要在错误信息中透露是用户名不存在还是密码错误这属于安全信息泄露。统一返回“认证失败”即可。5.4 性能与安全考量Token验证的性能JWT的签名验证是计算密集型操作。对于每个API请求都进行完整的JWT解析和签名验证可能会成为性能瓶颈。可以考虑在验证通过后将解析出的用户信息如username缓存在一个线程安全的缓存如ConcurrentHashMap中Key为Token本身或Token的哈希值并设置一个较短的缓存时间如5分钟。这样在Token有效期内同一Token的重复请求可以快速通过缓存验证。密钥轮换出于安全考虑JWT签名密钥应定期更换。在轮换期间新旧密钥需要同时支持一段时间。可以在TokenService中维护一个密钥列表验证时依次尝试。生成新Token时只使用最新密钥。防止Token泄露务必使用HTTPS来传输Token。避免将Token存储在容易被XSS攻击获取的地方如LocalStorage可以考虑使用HttpOnly的Cookie但这会与纯API客户端的用法产生矛盾需要权衡。对于敏感操作应要求二次认证。整合Spring Security 3.2.9同时支持Form和Token登录是一个深入理解Spring Security工作机制的绝佳实践。它要求你打破“非此即彼”的思维从请求的生命周期和过滤器链的层面去设计认证流程。核心在于优先级控制和差异化配置让Token过滤器以高优先级处理API请求并阻止后续的Session相关流程同时为Web请求保留完整的Form登录和Session管理流程。这种架构不仅满足了多样化的客户端需求也为系统从传统单体应用向现代化微服务架构平滑演进奠定了基础。
