排查一个线上问题时,同事把浏览器里复制的请求头整段贴进了工单,其中包括 Authorization: Bearer demo.SZGYb3RIGnVljxx-g_XlztcHHFppmx3ttJ_7_fpZGRU。工单系统对所有研发开放,这段令牌等于把账号交了出去。更让人后背发凉的是,这个令牌是半年前登录时签发的,现在仍然有效,因为签发逻辑里根本没有过期时间。

同一套代码里还有第二个问题:登录时把用户输入的密码和数据库里存的密码直接做字符串比较,数据库里存的就是明文。只要有人拿到一次数据库备份,所有账号就都泄露了,连重置都不用等。这两个问题都不是「实现得不够优雅」,而是明确的安全缺陷,必须在项目上线前改掉。

这一篇用最少的依赖做一个能跑通的鉴权:登录发令牌、过滤器校验签名、注解标权限。需要先说明,这台机器上没有引入 Spring Security,下面的方案是为了讲清「每一层该做什么」的最小实现,不是生产推荐。真正上线要换成 Spring Security 加 BCrypt,第四步会讲改动代价。

先分清认证和授权

认证解决「你是谁」,授权解决「你能做什么」。登录属于认证,接口权限属于授权,两者经常被混成一句「鉴权」,结果代码里到处是判断,谁也说不清哪一层负责什么。分开之后,职责就很清楚:认证在请求进入时完成一次,授权在每次操作时按资源判断。

会话(session)是服务器记住「你已经登录过」的状态。传统做法是登录后发一个 session id 放在 Cookie 里,服务器内存或 Redis 存一份对应的用户信息。令牌(token)是另一种做法:把用户身份和签名放在一个字符串里交给客户端,服务器不存状态,每次请求校验签名即可。前者好吊销,后者好扩展,代价不同。

这一篇选无状态令牌,因为它适合多实例部署:任何一台机器拿到令牌都能独立校验,不需要共享会话存储。代价是「主动踢人」变难,令牌一旦签发,在过期前一直有效。后面会给出补偿办法,但先把这个代价说清楚,避免以为令牌是免费方案。

登录:密码怎么存,令牌怎么签

密码永远不能明文存,也不能明文比较。正确做法是用单向哈希加盐:存的时候算出哈希,登录时用同样的参数再算一次,比较哈希值。BCrypt 是常用选择,它的特点是可以调工作因子,让每次计算故意慢一点,暴力破解的成本随参数上升。明文比较的问题不只是「泄露后直接被读」,还在于它无法抵抗撞库,攻击者拿一份泄露的密码表就能批量试。

工作因子怎么定?常见起点是 10 到 12,目标是在生产机器上单次校验耗时几十毫秒。太快等于没加成本,太慢会让登录接口在高并发下自己把自己拖垮。这个数字要按实际硬件测,不要照抄。盐不需要自己生成,BCrypt 每次编码会把随机盐写进结果串,校验时自动取出,同一密码两次编码的结果也不一样。

本机的最小实现为了少依赖,用 HMAC-SHA256 给用户名签名,令牌格式是 用户名.签名。HMAC 是一种带密钥的哈希:只有知道密钥的人才能算出正确签名,改一个字符签名就对不上。它解决的是「令牌不能被伪造」,并不解决「密码怎么存」,示例里的 demo/demo 只是占位。

package com.example.demo.auth;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class TokenService {
    private final SecretKeySpec key;

    public TokenService(@Value("${app.secret}") String secret) {
        this.key = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    }

    public String issue(String user) {
        return user + "." + sign(user);
    }

    public String verify(String token) {
        int dot = token.indexOf('.');
        if (dot <= 0) {
            return null;
        }
        String user = token.substring(0, dot);
        String sig = token.substring(dot + 1);
        String expected = sign(user);
        if (!MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8),
                sig.getBytes(StandardCharsets.UTF_8))) {
            return null;
        }
        return user;
    }

    private String sign(String user) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(key);
            return Base64.getUrlEncoder().withoutPadding()
                    .encodeToString(mac.doFinal(user.getBytes(StandardCharsets.UTF_8)));
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }
}

两个细节值得注意。第一,比较签名用 MessageDigest.isEqual 而不是 equals,前者是常量时间比较,避免通过响应时间差猜签名。第二,密钥从 app.secret 读,对应环境变量 APP_SECRET,不能写死在代码或 yml 里;多实例必须用同一个值,否则 A 机器签的令牌 B 机器不认。

登录接口只负责校验凭据和签发。示例里的账号密码是写死的,真实项目应查用户表并比对哈希。注意失败时不要区分「用户不存在」和「密码错误」,两种都返回同一个提示,避免攻击者用响应差异枚举账号:

package com.example.demo.auth;

import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;

@RestController
public class LoginController {
    private final TokenService tokens;

    public LoginController(TokenService tokens) {
        this.tokens = tokens;
    }

    @PostMapping("/api/login")
    public Map<String, Object> login(@RequestBody LoginRequest req) {
        if (!"demo".equals(req.user()) || !"demo".equals(req.pass())) {
            throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
        }
        return Map.of("token", tokens.issue(req.user()));
    }

    public record LoginRequest(String user, String pass) {}
}

实际返回的令牌就是本机跑出来的那一个,签名值取决于当时的 APP_SECRET,你换一个密钥就会得到不同的一串,但长度和格式一致:

curl -s -X POST 127.0.0.1:8081/api/login \
  -H "Content-Type: application/json" -d '{"user":"demo","pass":"demo"}'
{"token":"demo.SZGYb3RIGnVljxx-g_XlztcHHFppmx3ttJ_7_fpZGRU"}

这一篇没有数据库和额外的安全库,依赖只有 web 和 actuator,签名用的是 JDK 自带的加密包。打包和启动命令与前面一样:

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.3.5</version>
</parent>
<properties>
  <java.version>21</java.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
</dependencies>

$env:APP_SECRET = "change-me"
mvn -q -DskipTests package
java -jar target/demo-0.0.1.jar
这个令牌只包含用户名,没有过期时间,也没有角色信息。它能证明「这个字符串是服务器签的」,但不能证明「现在仍然有效」。这是示例为了讲清签名而做的简化,不能当成上线方案。

校验:放在过滤器,不要放在控制器

令牌校验放在过滤器,理由和上一篇讲权限分层时一样:它在路由之前执行,能统一覆盖所有受保护路径,不用每个方法都写一遍。过滤器做三件事:从 Authorization 头取出 Bearer 令牌、校验签名、把解析出的用户放进请求属性,供后面的控制器读取。

认证相关代码单独一个包,不要散落在控制器里。目录大致是这四层:

controller:登录与业务接口
auth:签发、校验、过滤器
config:密钥绑定与过滤器注册
web:统一异常与错误响应

响应体必须固定。no token 和 bad token 两种失败分开报,客户端能区分「没登录」和「令牌失效」,但都不要带上内部细节,比如签名算法、期望值、用户是否存在。错误信息越具体,攻击者越容易试探。

package com.example.demo.auth;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public class TokenFilter extends OncePerRequestFilter {
    private final TokenService tokens;

    public TokenFilter(TokenService tokens) {
        this.tokens = tokens;
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return !request.getRequestURI().startsWith("/api/me");
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request,
            HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        String header = request.getHeader("Authorization");
        if (header == null || !header.startsWith("Bearer ")) {
            write(response, "no token");
            return;
        }
        String user = tokens.verify(header.substring(7));
        if (user == null) {
            write(response, "bad token");
            return;
        }
        request.setAttribute("user", user);
        chain.doFilter(request, response);
    }

    private void write(HttpServletResponse response, String message) throws IOException {
        response.setStatus(401);
        response.setContentType("application/json");
        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
        response.getWriter().write("{\"error\":\"" + message + "\"}");
    }
}

控制器只读属性,不再判断令牌。这样接口本身不关心认证,测试时可以直接给属性赋值,不必构造完整请求头:

@RestController
public class MeController {
    @GetMapping("/api/me")
    public Map<String, Object> me(@RequestAttribute("user") String user) {
        return Map.of("user", user);
    }
}

三条请求的实际返回如下。带正确令牌是 200,不带是 401 且 no token,伪造一段签名是 401 且 bad token。第三种最容易写成 500,因为解析和比较可能抛异常,过滤器里必须把异常路径也转成固定响应。

curl -s 127.0.0.1:8081/api/me \
  -H "Authorization: Bearer demo.SZGYb3RIGnVljxx-g_XlztcHHFppmx3ttJ_7_fpZGRU"
{"user":"demo"}

curl -s 127.0.0.1:8081/api/me
{"error":"no token"}

curl -s 127.0.0.1:8081/api/me \
  -H "Authorization: Bearer demo.forged"
{"error":"bad token"}

过滤器路径匹配要写清楚。startsWith("/api/me") 只保护这一个接口,新增接口时很容易忘记加进来,结果新接口裸奔。更稳的做法是默认保护 /api 下的全部路径,用白名单排除登录、健康检查和公开查询,白名单要显式列出,宁可多写一行,不要漏保护一片。

取令牌时还有两个细节。Bearer 后面必须有一个空格,header.substring(7) 跳过的正是这七个字符;前缀判断区分大小写,客户端写成小写 bearer 会被判为没带令牌。如果服务前面有反向代理,确认代理没有把 Authorization 头过滤掉,有些默认配置会丢掉非标准头,表现就是「本地能过、线上全 401」。

授权:方法级注解,业务级判断

认证通过只说明「你是 demo」,不代表「demo 能删别人的数据」。方法级权限用注解表达:在需要角色的方法上标 @RequireRole("admin"),拦截器读取 HandlerMethod 上的注解,比对当前用户的角色,不匹配就返回 403。这样权限规则跟着方法走,代码评审时一眼能看到。

注解只适合「角色能不能访问这个方法」这种粗粒度判断。「这个订单是不是你的」属于数据级权限,必须放业务层,因为它要查数据库。把数据级判断硬塞进注解,要么注解里写死业务逻辑,要么拦截器里再查一遍数据库,两种都把简单问题复杂化。

角色信息从哪来?示例令牌里没有角色,所以只能查库或查缓存。这就是无状态令牌的一个现实成本:为了让令牌小,身份信息放得少,每次请求就要多一次查询。常见折中是令牌里放用户 ID 和角色,角色变更时接受短暂的不一致,或者用较短的过期时间加快收敛。

角色变更还有一个坑:撤销管理员权限后,旧令牌里如果还带着 admin,用户在过期前仍然是管理员。解决办法是缩短令牌寿命,或者在校验时查一次当前角色。前者增加刷新频率,后者增加数据库压力,两种都要付代价。不要既不查也不缩短,那等于权限变更永远不生效。

为什么现在不用 Spring Security

Spring Security 是 Spring 生态的标准方案,它把认证、授权、密码编码、CSRF、会话固定、记住我等事情都封装好了。本文不用它,是因为引入之后大部分代码会变成配置,反而不容易看清「请求在哪一层被拦、身份在哪一步建立」。先用最小实现走一遍,再换过去,迁移时知道每个配置项对应原来的哪段逻辑。

真正的上线改造包含四块。第一,把过滤器换成 SecurityFilterChain,用 authorizeHttpRequests 声明路径规则,白名单和角色规则都集中在配置里。第二,密码从明文迁到 BCrypt,历史数据不能直接转,因为明文哈希后仍可逆推出原密码的风险依旧存在,稳妥做法是强制用户下次登录时重置,或用 DelegatingPasswordEncoder 做过渡。第三,令牌加过期时间、刷新机制和吊销名单,这三项都要改签发和校验两处。第四,补测试,尤其是 401 和 403 的分支。

这套改造的工作量大约是把现在的认证相关代码重写一遍,业务控制器基本不动。如果团队里没人熟悉 Spring Security,建议在项目早期就上,不要等到接口几十个、用户几万个再迁;越晚迁,密码迁移和会话兼容的成本越高。

换过去之后,一些隐性的默认保护也一起拿到了:CSRF 防护、会话固定攻击防护、安全响应头、默认的密码编码器、登录失败处理。这些自己实现不仅费时间,还很容易漏。反过来说,Spring Security 的配置一旦写错,可能把整个路径放行或全部拦截,所以迁移后必须逐条验证白名单和受保护路径,不能只看「登录能通」。

Spring Security、BCrypt、JWT 刷新与吊销这套生产方案未在本机实测。本文实测的只有 HMAC 签名的最小实现和上面那几条 curl 返回。生产方案的代码结构按官方文档书写,落地前需要在目标环境完整验证。

令牌和密码出错时先看什么

下面这张表按现象查。认证问题的排查顺序是「请求有没有带令牌、令牌有没有到过滤器、签名对不对、用户状态还有效吗」,四步走完再去看权限。

现象真实原因第一步查什么
不带令牌返回 401 和 no token过滤器没匹配到该路径看 shouldNotFilter 和请求 URI
令牌正确但仍返回 401多实例的密钥不一致,或密钥被换过比对各实例的 APP_SECRET
伪造令牌返回 500 而不是 401解析异常没有转成固定响应看 verify 的异常分支
登录接口返回 415请求没带 JSON 的 Content-Typecurl 加 -H "Content-Type: application/json"
数据库里能直接读到密码存的是明文,没有做哈希查 users 表的密码字段
半年前的令牌还能用令牌里没有过期时间解码令牌内容看有没有 exp
禁用用户后仍能访问只在登录时查了用户状态校验令牌时是否复查状态或版本号
日志和工单里出现完整令牌打印了 Authorization 头或放进 URL搜日志配置和前端请求代码
换一台实例后登录态丢失会话存在单机内存,没有共享看 session 存储和负载均衡策略

这张表里第五、第六行是这篇的重点。它们不是「配置项没调对」,而是设计缺陷:明文密码和无过期令牌都不会因为加一台机器或改一个参数而变安全。发现这两条,应该直接排进修复计划,而不是留到下次重构。

还有一个顺序建议:先修密码存储,再修令牌过期,最后补限速和日志脱敏。前两项决定「泄露一次会不会永久失守」,后两项决定「攻击者能试多少次」。顺序反了也能做,但先做限速只是在拖时间,根上的问题还在。

边界与代价

无状态令牌最大的代价是不可吊销。用户改密码、账号被盗、员工离职,已签发的令牌在过期前依然有效。补偿办法有三种:把过期时间设短,比如十五分钟,用刷新令牌换新;维护一个吊销名单,校验时查一次缓存;在用户表加一个版本号,改密码时加一,令牌里带版本号,版本对不上就拒绝。三种都要多一次查询或存储,纯无状态就变成了「近似无状态」。

会话

登录后在服务端存一份状态,退出即删。好处是能立刻踢人、权限变更马上生效。代价是每台实例都要共享存储,多一次 Redis 往返,存储本身成了新的故障点。

无状态令牌

身份和签名放在客户端,任何实例都能独立校验,扩展方便。代价是签发后难以撤回,必须靠短过期、吊销名单或版本号补上,纯无状态会变成近似无状态。

过期时间怎么定?常见组合是访问令牌十五分钟、刷新令牌七天。太短会让客户端频繁刷新,刷新接口本身成为攻击面;太长等于没有过期。这两个数字不是定律,要按业务风险调整:金融类可以更短,内部工具可以稍长。关键是「有」,而不是精确到分钟。

令牌放哪里也有取舍。放 localStorage 实现简单,但页面里任何一段脚本都能读到,一旦有 XSS 就等于令牌泄露。放 HttpOnly Cookie 能挡住脚本读取,但要处理 CSRF,跨站请求会自带 Cookie。常见组合是 HttpOnly Cookie 加 SameSite,再对写操作校验 CSRF 令牌。没有一种放法能同时解决 XSS 和 CSRF,只能按威胁模型选。

会话方案并没有过时。单机或实例不多、需要即时踢人、用户量可控时,session 加 Redis 更简单:登录写 Redis,请求查 Redis,退出删 key。代价是每次请求多一次 Redis 往返,以及 Redis 成为新的故障点。选令牌还是会话,本质是选「扩展性」还是「可控性」,不是新旧之分。

还有一个经常被忽略的成本:登录接口本身要防暴力破解。同一个 IP 或同一个账号连续失败要限速,失败次数要记录,必要时要锁定一段时间。只做密码校验不做限速,等于把撞库的门开着。限速放在网关或应用层都可以,但必须有,且阈值要能调整。

最后是传输。令牌在 HTTP 明文里传,等于每次请求都在广播密码。生产必须 HTTPS,内网也要,因为内网不等于可信网络。反向代理终止 TLS 时,要确保应用拿到的协议头正确,否则生成的跳转链接可能还是 http,把用户送回明文。

当天能自己验证的练习

  1. 用固定密钥启动服务,连续登录两次,确认两次令牌完全相同,理解「无状态」意味着同一身份签出同一个串。
  2. 改掉 APP_SECRET 重启,再用旧令牌请求 /api/me,确认返回 bad token,理解密钥就是信任根。
  3. 把 shouldNotFilter 改成只排除 /health,访问 /health 和 /api/me,对比两条路径是否被拦。
  4. 手动把令牌最后一位改掉,请求 /api/me,确认是 401 而不是 500,再看过滤器里的异常分支。
  5. 在日志配置里打开请求头打印,发一次带令牌的请求,确认令牌出现在日志里,然后关掉这项配置并记录原因。

小结

三句话收束:认证在过滤器完成一次,授权分方法级和数据级两层,控制器不写令牌判断;密码必须哈希存储,令牌必须有过期和吊销手段,示例里的明文和永久令牌只是教学简化;自己签令牌适合理解和过渡,上线应换 Spring Security 加 BCrypt,并接受一次认证层的重写。

下一篇讲后台任务。认证解决的是「请求是谁」,但很多工作不该在请求线程里做:发邮件、生成报表、清理数据,这些要挪到后台。那篇会从「异步方法里混进一个阻塞调用,整个接口变慢」讲起,说清线程池、定时任务和重启丢任务的边界。