1. 为什么Session认证撑不住了一次多端登录事故引发的重构先讲个我自己的经历。之前维护过一套老管理系统认证方式是最经典的HttpSession用户登录后把用户信息塞进Session后续每个请求靠JSessionID去服务端内存里找对应的会话。单机部署、用户量不大时一切岁月静好直到某天业务扩张同一账号需要同时被几个办公室的人登录使用问题像连环爆一样出现——A在电脑上登录后B在另一台电脑登录A这边突然被踢下线有时候用户什么都没干过一会儿就提示会话过期后台日志里挤满了Session already invalidated之类的报错。排查到最后问题根因很清楚Session是服务端状态而服务端状态在分布式部署下天然难搞。当时系统虽然还没上集群但Nginx已经挂了多实例在做轮询转发用户的请求被负载到不同实例上而Session默认只存在第一次接收请求的那台机器内存里。哪怕后来引入了spring-session-data-redis做会话共享也只是把服务端有状态这个从根上就麻烦的问题延后了。更关键的是Session机制天然和Cookie绑定移动端App、第三方接口调用、小程序这些非浏览器场景处理Cookie的成本极高动不动就要手动维护会话标识烦不胜烦。正是这次事故让我下决心重构认证方案彻底抛弃Session改用Token认证具体实现就是Spring Security JWT。如果你也遇到类似问题——多端互踢、会话共享困难、非浏览器客户端难以接入或者单纯觉得传统Session认证不够灵活那么这篇文章应该能帮到你。我会从原理讲到落地把核心代码、配置细节和上线后踩过的坑一次说清楚。1.1 先弄明白会话迁移背后的思维转换Session认证和Token认证最本质的区别一句话就能概括Session是服务端记住你是谁Token是客户端自证你是谁。Session模式下用户登录后服务端生成一个ID也就是JSessionID返回给浏览器服务端自己存一份userId - 用户数据的映射。下次请求带上这个ID服务端查表、比对、放行。这里有个隐含前提服务端必须记住每一个已登录用户的状态所以Session叫有状态认证。Token模式完全不同。用户登录后服务端把用户ID、过期时间、签名等信息打包成一个字符串也就是JWT返回给客户端服务端自己不存任何东西。后续请求只要带上这个字符串服务端验签通过、确认没过期就信任这个请求的身份。所以Token叫无状态认证——服务端不需要记住谁只需要会验证。这个转变带来的直接好处有两个。第一天然支持多端同时登录因为每个Token是独立签发的彼此不冲突不像Session那样一个会话只能有一个归属第二天然适合分布式环境因为验证Token只需要密钥任何一台服务器都能独立完成校验不需要共享存储。这俩痛点恰好是上面那次事故的直接解药。1.2 Session和Token的对比一张表看懂我用一个表格把两者核心差异列清楚方便你遇到技术选型时直接对照对比维度Session认证Token认证JWT服务端状态有状态需要存储会话无状态服务端不存储多端登录默认互踢需要额外设计天然支持分布式扩展需要Session共享方案无需额外依赖跨端适配依赖Cookie移动端麻烦请求头传输全端通用注销处理删除Session即可立刻生效Token未过期前难以立即失效安全性会话标识泄露可被伪造利用依赖签名篡改会被识破看到最后一行你可能会有疑问既然Token不能立即失效那注销登录怎么办这个问题我放到后面专门讲属于Token认证最容易被忽略、也最容易踩坑的细节。2. 先摸清Spring Security的家底过滤器链与认证流程很多人觉得Spring Security难不是难在写代码而是难在它是一个天生就带着完整流程的框架你得顺着它的流程做事。所以先花一点篇幅把它的核心机制讲清楚后面实现起来才不会云里雾里。2.1 过滤器链认证其实发生在请求进入Controller之前Spring Security对请求的拦截靠的是一条很长的过滤器链Filter Chain。一个请求到达你的Controller之前会先经过这条链上一个接一个的过滤器每个过滤器只干一件事然后传给下一个。你可以把它想成进机场安检——你还没到登机口就已经过了好几道查验身份核验、行李扫描、随身物品检查任何一道不过都进不去。这条链上几个关键的过滤器大概是这样的顺序SecurityContextPersistenceFilter负责从请求里恢复上下文UsernamePasswordAuthenticationFilter负责处理表单登录BasicAuthenticationFilter负责处理HTTP Basic认证ExceptionTranslationFilter负责把异常转成合适的HTTP状态码AuthorizationFilter负责最终的权限判断。对我们做Token认证来说最重要的动作是把我们自定义的JWT校验逻辑作为一个过滤器插入到这条链中合适的位置。具体插在哪后面写代码的时候细说。2.2 SecurityContextHolder一个线程私有的小黑板过滤器链上那么多环节它们之间怎么传递当前这个请求是谁这个信息靠的是SecurityContextHolder。它本质上是个基于ThreadLocal的容器每个请求线程都有自己的一个小黑板——SecurityContext里面放着当前用户的认证信息Authentication。你的业务代码里随时能通过SecurityContextHolder.getContext().getAuthentication()拿到当前登录用户原理就在这。但这里有一个非常隐蔽的坑ThreadLocal是线程私有的如果某个请求线程处理完了没有清理上下文而线程池复用了这个线程下一个请求就可能读到上一个请求的登录信息造成用户身份串号。Spring Security在过滤器链的末尾有清理逻辑但如果你是自己手动往SecurityContextHolder塞东西一定要记得在finally块里清空或者确保你的过滤器包裹在框架清理逻辑之内。2.3 我们要重新定义的认证流程应该长什么样理解了过滤器链和SecurityContextHolder之后基于Token的认证流程其实就可以自己推导出来了客户端登录带着用户名密码访问登录接口。服务端校验用户名密码成功后签发一个JWT返回给客户端。客户端后续每次请求在请求头里带上Authorization: Bearer JWT。服务端有一个专门的过滤器就是我们要写的JwtAuthenticationFilter拦截所有请求从请求头里取出JWT。过滤器验证JWT的签名和有效期。如果没问题就解析出用户信息造一个Authentication对象塞进SecurityContextHolder。后续的授权过滤器AuthorizationFilter根据SecurityContextHolder里的信息判断该不该放行。你会发现整个流程里Spring Security框架只帮你处理了第6步和一部分第1步第4、5步是需要自己实现的。不过别慌这部分代码量不大核心就一个过滤器和一个工具类。3. 手写JWT工具类结构、签名与校验市面上操作JWT的Java库不少我用得最多的是jjwt因为它API设计直观、文档齐全、社区活跃。下面所有代码基于jjwt 0.11.x版本如果用了其他版本API会有差异这点留意一下。先在pom.xml里加依赖dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.11.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.11.5/version scoperuntime/scope /dependency3.1 JWT三段式结构拆解一个JWT字符串长这样用点号分成三段eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiaWF0IjoxNzAwMDAwMDAwLCJleHAiOjE3MDAwMDM2MDB9.签名部分Header第一段声明签名算法和令牌类型典型内容是{alg:HS256,typ:JWT}。Payload第二段放实际的数据比如用户ID、用户名、签发时间iat、过期时间exp等这一部分只是Base64编码不是加密的任何拿到Token的人都能解码看到内容所以绝对不要放密码之类的敏感信息。Signature第三段对前两段做签名计算。服务端持有密钥把前两段内容和密钥一起丢进签名算法算出一串摘要放进第三段。为什么叫防篡改因为有人改动了Payload里的任何一个字符重新计算后的签名和第三段对不上服务端一验签就识破了。当然前提是密钥绝对不能泄露。3.2 选择HS256的权衡与实现JWT常用签名算法有HS256对称加密和RS256非对称加密。对称的意思是加密和解密用同一个密钥非对称则是公钥加密、私钥解密。单体应用、前后端分离项目、没有第三方系统需要独立验签的场景用HS256完全够用配置简单、性能好。如果以后有多个服务需要各自独立验证Token那就要考虑RS256——每个服务只持有公钥验签公钥随便分发私钥只要保存在签发中心。网上很多教程默认只讲HS256我建议你架构上如果有多服务共存的规划提前想清楚这一点不然后面重构验签逻辑会动到所有服务的配置。下面是我用的JwtUtil工具类基于HS256Component public class JwtUtil { Value(${jwt.secret}) private String secret; Value(${jwt.expiration}) private Long expiration; // 单位秒 Value(${jwt.header}) private String header; public String generateToken(String userId, String username) { Date now new Date(); Date expiryDate new Date(now.getTime() expiration * 1000); Key key Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8)); return Jwts.builder() .setSubject(userId) .claim(username, username) .setIssuedAt(now) .setExpiration(expiryDate) .signWith(key, SignatureAlgorithm.HS256) .compact(); } public Claims parseToken(String token) { Key key Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8)); return Jwts.parserBuilder() .setSigningKey(key) .build() .parseClaimsJws(token) .getBody(); } }这里有几个细节值得展开说。第一signWith方法的坑。jjwt 0.10之前的老写法是signWith(SignatureAlgorithm.HS256, secret)直接传字符串密钥但这种写法在新版本里已经废弃了而且它内部会把字符串当作字节数组用密钥太短会直接抛异常。正确做法是像我这样用Keys.hmacShaKeyFor(...)把密钥字节数组转成Key对象。HS256要求密钥长度至少32字节所以配置里的jwt.secret别偷懒写个abc123就完事建议用一个不少于32位的随机字符串。第二.setSubject(userId)和.claim(username, username)怎么选。Subject是JWT规范里约定好的字段我习惯放唯一标识用户ID因为它是主键、不长、不随用户名变更而变化。用户名通过自定义claim放进去方便后续业务直接展示。别的角色、邮箱、部门等字段都可以用claim方式塞进去但一定要克制——Token越短越好塞太多无关信息会让请求头体积膨胀而且Payload里的东西等于公开的别放敏感数据。3.3 过期时间的策略与会话并发过期时间expiration不是随便拍脑袋定的。太短用户频繁重新登录体验差太长Token泄露后有效期过长风险大。我个人习惯普通后台管理系统设2小时左右需要较长会话的可以设24小时但一定要配套刷新机制。很多项目上线后出现用户明明一直在用却突然被要求重新登录的抱怨多半就是因为没有刷新机制Token过期后没有自动续期。刷新机制的做法很多我提供一个简单版本在登录接口的响应里同时返回accessToken和refreshTokenaccessToken短期有效比如2小时refreshToken长期有效比如7天。每次请求如果accessToken过期了客户端用refreshToken去换新的accessToken。这个方案逻辑清晰但代码量会多一点。如果项目刚起步可以先用一个过度方案Token有效期设长一点等用户量起来、对安全要求明确后再做完整刷新。4. 落地核心代码SecurityConfig JwtAuthenticationFilter工具类有了接下来是真正让Spring Security跑起来的部分一共三块配置类、登录接口、认证过滤器。这三块配合好整个认证链路就通了。4.1 配置类关掉什么、放开什么、加什么过滤器直接上代码这是基于Spring Security 5.7推荐的新写法用SecurityFilterChainBean替代继承WebSecurityConfigurerAdapter后者在新版本里已经废弃Configuration EnableWebSecurity public class SecurityConfig { Autowired private JwtAuthenticationFilter jwtAuthenticationFilter; Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http.csrf().disable() .cors().and() .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() .authorizeRequests() .antMatchers(/api/auth/login, /api/auth/refresh).permitAll() .antMatchers(/doc/**, /error).permitAll() .anyRequest().authenticated() .and() .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class); return http.build(); } Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }逐行解释一下每个配置的意图csrf().disable()。CSRF防护是防止跨站请求伪造的它的原理依赖Session——给页面渲染时注入一个随机token提交表单时校验。但我们现在做的是前后端分离、Token认证请求头里已经带了AuthorizationCSRF防护反而会碍事尤其是接口被前端用multipart/form-data调用时没有CSRF token就直接403。所以静态分析社区里有个共识无状态Token认证下CSRF防护基本可以关掉。sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)。这句话非常关键它告诉Spring Security不要创建也不要使用Session。你可能会想我们本来就没打算用Session不写这句不行吗不写还真不行——Spring Security默认的很多机制都会去找Session用不显式声明无状态它可能悄悄给你创建Session导致明明是无状态认证服务端却总有会话残留的尴尬局面。authorizeRequests()里.permitAll()和.authenticated()。登录、刷新Token这些接口必须放行不然用户连登录都进不来其余接口全部要求认证后才可访问。这是个最简版规则实际项目中你还可以针对不同接口做细分比如/api/admin/**放行管理员角色、/api/user/**放行普通用户角色用.hasRole(ADMIN)这类方法。addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)。这句话决定了过滤器插队的位置插在UsernamePasswordAuthenticationFilter之前。为什么插这里因为UsernamePasswordAuthenticationFilter是用来处理表单登录的而我们不需要它处理Token必须让JwtAuthenticationFilter先于它执行——先把Token解析成认证信息塞进上下文后面框架再做授权判断时数据就齐了。网上有些人插在BasicAuthenticationFilter后面也有人直接插在最前面效果类似但我还是建议插在UsernamePasswordAuthenticationFilter前面这是最符合登录流程被自定义认证替代这一语义的位置。4.2 登录接口Token从哪里来登录接口做的事可以拆成四步接收用户名密码、校验参数、匹配密码、签发Token。一个简化版实现RestController RequestMapping(/api/auth) public class AuthController { Autowired private UserService userService; Autowired private JwtUtil jwtUtil; Autowired private PasswordEncoder passwordEncoder; PostMapping(/login) public ResponseEntity? login(RequestBody LoginRequest request) { User user userService.findByUsername(request.getUsername()); if (user null || !passwordEncoder.matches(request.getPassword(), user.getPassword())) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED) .body(new ApiResponse(401, 用户名或密码错误, null)); } String token jwtUtil.generateToken(user.getId(), user.getUsername()); return ResponseEntity.ok(new LoginResponse(token, jwtUtil.getExpiration())); } PostMapping(/logout) public ResponseEntity? logout(RequestHeader(Authorization) String authorization) { // 前端的logout逻辑客户端丢弃Token即可 return ResponseEntity.ok(new ApiResponse(200, 注销成功, null)); } }两个细节说明。密码校验一定不能用明文比对必须用PasswordEncoder的matches方法。我推荐BCryptPasswordEncoder它内部会自动加盐、自动生成格式化的哈希串同一个密码每次比对生成的哈希都不一样安全性可靠。新手容易犯的错误是直接把数据库里的密码拿出来和用户输入的字符串做equals一旦这么干数据库泄露等同于密码全部泄露。关于logout接口。如果你仔细想想就会发现在纯无状态Token方案里服务端是无法让一个已经签发的Token失效的Token就像一张盖了章的餐券在到期之前拿着它随时能进门。所以最基础版的注销就是前端把本地存的Token删掉服务端什么都不用做。但这样做有个问题如果用户的Token被偷了偷的人拿它来调接口服务端照样放行。要解决这个问题就得引入Token黑名单机制——在服务端维护一个黑名单列表Token被注销后加进去每次请求来的时候查一下。这个机制后面第5节展开讲。4.3 JwtAuthenticationFilter每次请求的查证逻辑这个过滤器是整个方案的心脏也是唯一一段需要跨OncePerRequestFilter实现的逻辑Component public class JwtAuthenticationFilter extends OncePerRequestFilter { Autowired private JwtUtil jwtUtil; Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String token resolveToken(request); if (token ! null SecurityContextHolder.getContext().getAuthentication() null) { try { Claims claims jwtUtil.parseToken(token); String userId claims.getSubject(); String username claims.get(username, String.class); if (userId ! null) { UserDetails userDetails new UserDetails() { // 实现必要的方法可以简化 }; UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities()); authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request)); SecurityContextHolder.getContext().setAuthentication(authentication); } } catch (JwtException | IllegalArgumentException e) { SecurityContextHolder.clearContext(); } } filterChain.doFilter(request, response); } private String resolveToken(HttpServletRequest request) { String bearer request.getHeader(SecurityConstants.HEADER_STRING); // Authorization if (StringUtils.hasText(bearer) bearer.startsWith(Bearer )) { return bearer.substring(7); } return null; } }几个容易写错的地方我都标记一下第一OncePerRequestFilter的意义。直接实现Filter接口的话一个请求可能被这个过滤器执行多次比如转发场景下。OncePerRequestFilter保证一个请求线程只执行一次过滤器逻辑避免重复解析Token。这一点在Spring Cloud Gateway之类的网关场景里尤其关键。第二Token解析失败的处理。parseToken只要验签不过、过期、格式错误都会抛异常。我在catch块里做了SecurityContextHolder.clearContext()然后把请求继续往下传。你不要一看到异常就直接返回401因为Spring Security后面还有ExceptionTranslationFilter在管异常转换——你把请求放行它会根据有没有认证信息来决定是继续走还是返回401这样更符合框架语义。当然你也可以在过滤器里直接写response.sendError(401)效果一样但会让后面的授权过滤器失去意义。我个人的习惯是交给框架处理代码更干净。第三权限和角色的处理。上面代码为了方便阅读UserDetails那块被简化了。正常项目里你应该从数据库或Token的claim里加载用户角色填充到Authentication的authorities里这样后续才能用PreAuthorize(hasRole(ADMIN))或/admin/**这种规则做细粒度权限控制。如果Token里已经带了角色信息直接转换就行不用再查库如果为了角色变更实时生效那就从库拉时间换准确性二选一。5. 上线后遇到的坑与安全加固代码跑通只是第一步把方案上线到生产环境真正的问题才慢慢浮出水面。这里记录的每一段都是实际踩过坑之后沉淀下来的希望你能少走点弯路。5.1 第一个坑注销后Token依然有效怎么处理前面已经提到无状态Token理论上无法立即失效但业务上又需要注销后立刻不能访问的能力怎么解决我见过不少项目直接把Token失效需求砍掉理由是无状态就是这样但其实有个折中的方案引入一层轻量的服务端存储专门存黑名单Token。核心思路是注销时把Token的jtiJWT ID唯一标识或Token本身连同过期时间一起写进RedisTTL设成和Token剩余有效期一致。每次请求的过滤器里解析Token后先去Redis查一下这个Token在不在黑名单里在就直接拒绝。Redis查一次的开销极小而且如果选用spring-session-data-redis等组件接入成本也不高。假如你用的是spring-boot-starter-data-redis大致逻辑是这样// 注销时 redisTemplate.opsForValue().set(blacklist: token, 1, jwtUtil.getRemainingTime(token), TimeUnit.SECONDS); // 过滤器里 String blacklistKey blacklist: token; if (Boolean.TRUE.equals(redisTemplate.hasKey(blacklistKey))) { // 拒绝访问 }这个方案被业界大量采用也是Spring Security官方文档里提到如何在无状态认证下支持注销的常见解法。代价是多了一次Redis查询换来的是注销逻辑真正可控。我在实际项目中就是这么用的用户数量到了几十万级别Redis查询性能也扛得住。5.2 第二个坑密钥管理与续期策略密钥管理这件事很多教程一句放配置文件带过但生产环境绝不能这么随意。我把几个常见的错误和对应做法列出来错误做法问题正确做法密钥硬编码在代码里源码泄露密钥泄露放配置中心或环境变量代码只引用变量名所有环境用同一个密钥测试环境泄露生产环境沦陷用不同的密钥隔离环境密钥太短32字节HS256签名强度不足生成64位以上随机字符串无感知旋转密钥需要换Key时所有存量Token全部失效设计多密钥切换机制新旧Key共存过渡多密钥旋转的做法不复杂配置里维护一个issuer - secret的映射签发Token时用当前生效的那个Key验签时先根据Token里的kidKey ID找到对应的Key再来验证。这样换Key时旧Token还能继续验签直到过期不会造成大规模掉线。续期策略上我实践下来比较顺的方案是RefreshToken AccessToken双层前面已经提过。这里补一个具体设定AccessToken有效期2小时、RefreshToken有效期7天RefreshToken只允许用在/api/auth/refresh接口换取新的AccessToken换取时校验RefreshToken是否合法、是否在黑名单里RefreshToken一旦使用立即作废换发新的客户端定期在AccessToken过期前静默刷新。这套机制上线后用户基本感知不到过期这回事用户体验和安全性做到了平衡。5.3 第三个坑白名单和静态资源放行很多项目启动后出现一个玄学问题接口调通了但静态资源或某个特定路径死活进不去一直401。尤其是有Swagger文档、/actuator监控端点、websocket握手连接这类特殊路径的场景。原因很简单authorizeRequests()里的放行规则如果没配全Spring Security会默认拦下所有没有明确放行的请求。所以配置的时候要仔细梳理哪些路径是无需认证即可访问的。拿Swagger举例它暴露的不是一个路径而是一串/swagger-ui.html、/swagger-ui/**、/v3/api-docs/**、/webjars/**等漏一个就白屏。WebSocket握手请求也一样握手阶段没法带请求头鉴权或者说带了也不方便处理一般选择放行握手路径在消息层做业务鉴权。我自己吃过的亏是放行了/doc/**结果实际请求路径是/swagger-ui/index.html根本不匹配排查了半天最后发现是路径前缀不统一。所以我的经验是放行路径写成明确的、还原真实结构的不要想当然用通配符图省事。5.4 日志脱敏与请求头泄露上线后另一个容易忽视的安全点是日志系统把Token打了出来。项目中每个关键操作都打了请求日志某次排查问题时发现日志文件里User-Agent、Authorization、请求参数都记录着Token赫然在列。日志文件如果被有心人拿到等于直接把用户身份拱手相送。解决思路两招一起用第一全局日志过滤器做脱敏拦截HTTP请求内容检测Authorization字段值用*****替换后再进入日志第二日志配置过滤关键字在logback.xml里给authorization、token、password这些敏感字段加上过滤规则。这个措施看着简单但在我经历过一次客户安全审计之后才意识到它有多重要。5.5 关于CORS和失效响应状态码的坑前后端分离项目必然面对CORS跨域资源共享。我遇到过的问题是前端页面部署在http://localhost:8080接口服务在http://localhost:9000跨域环境下前端先发一个OPTIONS预检请求被安全配置拦截直接401真正的请求根本没发出去。解决方法很标准要么用CorsFilter统一处理要么在配置里加.cors()然后提供一个CorsConfigurationSourceBean。如果你用的是上面4.1节的配置cors().and()已经开启了但别忘了在CorsConfigurationSource里把允许的来源、请求头、请求方法都配好特别是允许的请求头里包含Authorization否则跨域请求带上Token照样被浏览器拦。最后一个细节401和403要分清。Token缺失或过期应该返回401未认证Token有效但权限不足应该返回403无权限。很多项目混用这两个状态码前端处理起来会非常混乱。正确区分的好处是前端拿到401就知道该跳登录页了拿到403就知道是权限不够不该乱跳。这个看着零碎但对联调效率影响很大。我在整个项目重构过程中最大的体会是Spring Security的复杂度不在于单个API怎么用而在于你要理解它背后的流程哲学然后顺着它的流程做扩展。Token认证本身不难难的是把无状态方案放到真实业务里处理注销、续期、密钥、跨域这些边角问题。希望这一整套下来你能少走一些我走过的弯路。
