第一个登录接口写完后,前端图省事,把 token 拼在跳转链接的查询串里:/dashboard?token=...。两天后查访问日志,发现整条令牌明晃晃地躺在 Nginx 的 access log 里,任何能看日志的人都能拿它冒充用户。另一个问题是校验函数只判断了「用户名是不是 demo」,签名部分根本没参与比较,把 token 末尾改几个字符,接口照样返回 200。
这两个问题都不是密码学难题,而是「令牌放在哪、校验什么、谁来校验」的工程选择。无状态令牌(stateless token)的意思是服务端不保存会话,只靠令牌本身携带的信息和签名判断身份。它的好处是水平扩展时不用共享会话存储;代价是签发之后很难立刻作废,过期、吊销、密钥轮换都要提前设计。
这篇在上一篇的数据层之上加鉴权:用 HMAC 给令牌签名,从 Authorization 头里取 Bearer 令牌,用 FromRequestParts 做提取器,把失败分成「没带 token」和「token 不对」两种 401。JWT 库方案不在本机实测范围内,会单独标注。
先看现象:鉴权层的九个典型故障
鉴权问题的共同点是「能跑通」和「安全」之间差着好几个细节。下面这张表按现象排,前四条是多数项目第一次上线前都会遇到的。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 令牌出现在访问日志或浏览器历史里 | 令牌放在查询串,被 URL 记录、代理日志、Referer 带出去 | 改成 Authorization: Bearer 头 |
| 改几个字符 token 仍然有效 | 校验只比较用户名或 payload,没有比较签名 | 看校验函数是否重新计算签名并比对 |
| 没带 token 也返回 403 | 把「未认证」和「无权限」混成一个状态码 | 未认证用 401,已认证但无权限用 403 |
| 重启服务后所有人掉登录 | 签名密钥每次启动随机生成,旧令牌全部失效 | 密钥是否来自固定的环境变量 |
| 令牌过期后仍能访问 | 令牌里没有过期时间,或校验时没检查 | payload 是否有 exp,校验是否比较当前时间 |
| 用户改密码后旧令牌还能用 | 无状态令牌不与用户状态关联,签发后独立有效 | 是否有版本号或吊销名单 |
| 前端自己改 cookie 里的用户 id 就提权 | cookie 没有签名,服务端直接信任其中的字段 | cookie 是否由服务端签名或改用 HttpOnly 会话 |
| 从 header 取 token 总是 None | 头名或前缀大小写不对,或多了空格 | 打印 HeaderMap,确认是 Bearer 加一个空格 |
| 每个 handler 都写一遍解析逻辑 | 鉴权写在业务函数里,新增接口容易漏 | 改成提取器或 route_layer |
这张表里最危险的是第二条和第七条。签名不校验,令牌就退化成一张写着用户名的纸条;cookie 不签名,前端可以随便改字段。两者都属于「看起来能用,实际上没有鉴权」。判断标准很简单:把令牌或 cookie 改一个字符,请求必须失败。
令牌放哪:header、cookie 还是查询串
三种常见位置各有代价。查询串最容易被记录:浏览器历史、服务器访问日志、反向代理日志、Referer 头,都会把 URL 原样保存。只要令牌出现在这些地方,就等于泄露。Cookie 会自动随请求发送,适合浏览器场景,但必须设置 HttpOnly 防止脚本读取,设置 Secure 只在 HTTPS 下发送,还要考虑 CSRF。Authorization 头不进入 URL,也不会被自动发送,适合前后端分离和移动端,是本文采用的方式。
选 header 还有一个现实好处:日志中间件通常只记录方法、路径、状态码,不记录头部,令牌不会顺手进日志。反过来,如果你自定义的日志把整个 HeaderMap 打印出来,那就等于把令牌写进日志,这个坑比查询串更隐蔽。日志里最多记录「有没有 Authorization」和令牌的前几位,不要记录完整值。
无状态令牌
服务端不存会话,身份信息放在令牌里,靠签名防篡改。扩容时不用共享存储,任何一台机器都能校验;适合 API、移动端、多实例部署。代价是吊销困难,签发后到过期前一直有效,必须靠短过期时间、版本号或黑名单补。
服务端会话
服务端保存会话,客户端只拿一个随机 id。可以随时在服务端删除会话,做到立即退出;权限变更也能立刻生效。代价是要有共享存储(Redis 或数据库),多实例部署时多一个依赖,每次请求多一次查询。
两者没有绝对优劣。用户量小、需要「立刻踢下线」的后台系统,服务端会话更省心;面向公网的 API、需要横向扩展、客户端不限于浏览器,无状态令牌更合适。很多系统会混用:短效令牌加刷新令牌,刷新令牌存服务端,既能快速失效,又不用每个请求都查库。本文只做短效令牌的最小版本,刷新流程不展开。
如果坚持用 cookie,必须同时处理 CSRF。cookie 会自动随请求发送,别的站点诱导用户点一个链接,就可能带着用户的 cookie 打到你的接口。常见防御是 SameSite=Lax 或 Strict、校验 Origin 头、给写操作加 CSRF token。用 Authorization 头则天然避开这个问题,因为浏览器不会自动把自定义头加进跨站请求。这也是本文选头部的另一个原因。
HMAC 签发与校验:签名到底签什么
HMAC 是一种带密钥的哈希:用同一个密钥对同一段内容计算,得到相同结果;没有密钥的人无法伪造。本文用 sha2 0.10 和 hex 0.4 拼一个简化版:令牌由「用户名 + 点 + 签名」组成,签名是「密钥、竖线、用户名」的 SHA-256 十六进制字符串。这不是标准 JWT,但足以说明签名、放置和校验的完整链路。
先加依赖:
cargo add sha2@0.10
cargo add hex@0.4
cargo run
[dependencies]
sha2 = "0.10"
hex = "0.4"
签发和校验的代码如下。登录只在用户名和密码都等于 demo 时发令牌,真实项目里应改成查用户表并校验密码哈希:
use sha2::{Digest, Sha256};
fn sign(secret: &str, body: &str) -> String {
let mut hasher = Sha256::new();
hasher.update(secret.as_bytes());
hasher.update(b"|");
hasher.update(body.as_bytes());
hex::encode(hasher.finalize())
}
fn issue(secret: &str, user: &str, pass: &str) -> Option<String> {
if user != "demo" || pass != "demo" {
return None;
}
let body = user.to_string();
Some(format!("{}.{}", body, sign(secret, &body)))
}
fn verify(secret: &str, token: &str) -> Option<String> {
let (user, signature) = token.split_once('.')?;
let expected = sign(secret, user);
if expected == signature {
Some(user.to_string())
} else {
None
}
}
登录接口把它包成 handler,密码校验成功才返回令牌:
use axum::{extract::State, http::StatusCode, Json};
use serde::{Deserialize, Serialize};
#[derive(Deserialize)]
struct Login {
user: String,
pass: String,
}
#[derive(Serialize)]
struct TokenBody {
token: String,
}
async fn login(
State(state): State<AppState>,
Json(input): Json<Login>,
) -> Result<Json<TokenBody>, StatusCode> {
match issue(&state.secret, &input.user, &input.pass) {
Some(token) => Ok(Json(TokenBody { token })),
None => Err(StatusCode::UNAUTHORIZED),
}
}
签发接口的实测返回如下。这里的签名值取决于本机使用的密钥和报文格式,你换一个 APP_SECRET 跑,十六进制部分会完全不同,但「用户名 + 点 + 64 位十六进制」的结构不变。所以看到长度不对、没有点、或者签名不是 64 位,先查签发逻辑,而不是怀疑客户端。
curl -s -i -X POST 127.0.0.1:18080/api/login -H "Content-Type: application/json" -d '{"user":"demo","pass":"demo"}'
HTTP/1.1 200 OK
content-type: application/json
{"token":"demo.cdf3d5a5ea0125acecb1223226d7a12b3ef37ef278d64aa90aa0c0d576631da5"}
校验函数里有一处必须说明:expected == signature 是普通字符串比较,遇到第一个不同字节就返回,理论上可以通过响应时间差逐字节猜出签名。这是简化版,真上线应改用 subtle 的常量时间比较,或者直接用成熟的 JWT 库。本文保留普通比较,是为了让代码短、逻辑清楚;安全强度上的这个折扣必须记住。
为什么用带密钥的 HMAC,而不是直接算 sha256(user):普通哈希谁都能算,攻击者知道你的格式后,可以自己给任意用户名算一个「签名」,服务端无法分辨。密钥的作用是让签名只有持有密钥的一方才能生成。密钥长度也要够,至少 32 字节的随机值,别用「secret123」这类可猜的字符串;生成可以用系统随机源,不要用时间戳。
APP_SECRET 注入,启动时读取一次放进 AppState;缺失就拒绝启动。密钥一旦泄露,所有人都能签出合法令牌,签名机制等于没有。从 Header 到 handler:用提取器接住身份
身份解析适合做成提取器,而不是每个 handler 开头复制一遍。下面实现 FromRequestParts:它只读请求头,不碰 body,因此可以放在参数列表里任意位置,也不会影响后面的 Json。失败时返回 (StatusCode, Json),这样错误体和项目其他接口保持一致。
use axum::{
extract::FromRequestParts,
http::{header, request::Parts, StatusCode},
Json,
};
use serde_json::json;
struct AuthUser {
user: String,
}
impl FromRequestParts<AppState> for AuthUser {
type Rejection = (StatusCode, Json<serde_json::Value>);
async fn from_request_parts(
parts: &mut Parts,
state: &AppState,
) -> Result<Self, Self::Rejection> {
let token = parts
.headers
.get(header::AUTHORIZATION)
.and_then(|value| value.to_str().ok())
.and_then(|value| value.strip_prefix("Bearer "))
.ok_or_else(|| {
(
StatusCode::UNAUTHORIZED,
Json(json!({ "error": "no token" })),
)
})?;
let user = verify(&state.secret, token).ok_or_else(|| {
(
StatusCode::UNAUTHORIZED,
Json(json!({ "error": "bad token" })),
)
})?;
Ok(AuthUser { user })
}
}
async fn me(user: AuthUser) -> Json<serde_json::Value> {
Json(json!({ "user": user.user }))
}
strip_prefix("Bearer ") 对大小写和空格敏感。HTTP 头部名本身不区分大小写,但值里的方案名按惯例写 Bearer;如果你的客户端发送 bearer,这里就取不到。排查「明明传了 token 却返回 no token」时,先把原始头部打印出来,确认前缀和空格,再怀疑解析逻辑。
把路由挂上:
let app = Router::new()
.route("/health", get(health))
.route("/api/login", post(login))
.route("/api/me", get(me))
.with_state(state);
实测三种请求。正常带 token:
curl -s -i 127.0.0.1:18080/api/me -H "Authorization: Bearer demo.cdf3d5a5ea0125acecb1223226d7a12b3ef37ef278d64aa90aa0c0d576631da5"
HTTP/1.1 200 OK
content-type: application/json
{"user":"demo"}
伪造 token(改动签名的最后一位):
HTTP/1.1 401 Unauthorized
content-type: application/json
{"error":"bad token"}
不带 token:
HTTP/1.1 401 Unauthorized
content-type: application/json
{"error":"no token"}
三种返回把失败原因分开了:「没带」是客户端忘了加头,「不对」是令牌本身有问题。这个区分对排查很有用,但对外说明时可以更模糊,避免告诉攻击者「你的签名错在哪一位」。日志里记录「无 token」「签名不匹配」就够,不要把客户端传来的完整令牌写进去。
用提取器而不是中间件,还有一个可测试性的好处:处理函数的参数里显式出现 AuthUser,测试时可以直接构造这个结构体,不必伪造一整套 HTTP 请求;而中间件通常要启动整个 Router 才能验证。代价是每个需要身份的 handler 都要在签名里写一个参数,忘写就没有身份,编译期不会提醒。缓解办法是把「需要身份」的接口收在一个子 Router 里,统一挂鉴权,再靠代码评审确认新接口归属。
AuthUser 做判断。把两者混在提取器里,会让权限逻辑散落且难以测试。过期、吊销与密钥轮换
无状态令牌的最大代价是「签发后无法收回」。解决方向有三个。第一,缩短有效期:把过期时间写进令牌内容,校验时比较当前时间,过期就返回 401。第二,维护版本号:用户表里存一个 token_version,令牌里也带版本,改密码或强制下线时把版本加一,旧令牌全部失效;代价是每个请求要查一次用户。第三,黑名单:把要作废的令牌 id 放进 Redis,设置到过期为止,校验时查一次;代价是多一个依赖和一次查询。
本文的简化版没有过期字段,这是它和真正可用方案之间最大的差距。补上过期时间的做法是:把 user 和 exp 一起放进签名内容,令牌格式变成 user.exp.signature,校验时先验签、再比较 exp 与当前时间。注意签名必须覆盖 exp,否则攻击者可以改过期时间而签名仍然有效。
密钥轮换要提前设计。最粗暴的做法是换掉 APP_SECRET,所有旧令牌立刻失效,用户重新登录;平滑的做法是同时接受新旧两个密钥一段时间,新令牌用新密钥签,校验时先试新密钥再试旧密钥,等旧令牌自然过期后移除旧密钥。这个机制需要代码支持,不能等到泄露那天才想。
客户端把令牌存哪里,也是会话设计的一部分。浏览器的 localStorage 读写方便,但任何 XSS 都能读到;HttpOnly cookie 脚本读不到,却要处理 CSRF。移动端可以放系统安全存储,不要放普通偏好设置。没有一种存储能同时免除 XSS 和 CSRF,选一种并接受它的风险,比「两边都想要」更现实。
为什么不要把用户信息塞进无签名的 cookie:cookie 只是一个客户端可读写的容器,没有签名就没有防篡改。前端把 {"user":"demo","role":"admin"} 编码进 cookie,服务端如果直接解析并信任,任何人改一下就成了管理员。要么用服务端签名(HMAC 或加密),要么改用服务端会话,只把随机 id 放进 cookie。把「用户信息」和「可信身份」混为一谈,是这类漏洞的根源。
边界与代价
这套方案适合中小规模的 API,但边界很清楚。第一,它不是标准 JWT,不能直接给第三方系统使用;要互通,应该换成成熟的 JWT 库,按标准生成和校验。JWT 库的具体选型和实际输出我没有在本机实测,不在这里给版本和代码,只提醒一点:库能帮你处理编码、签名算法和过期,但「密钥从哪来、令牌放哪、如何吊销」仍然要自己决定。
第二,普通字符串比较不是常量时间。本文为了代码短保留了这个简化,真上线要换 subtle 或库实现。这个差别在本地几乎测不出来,但在公网环境下是可以被统计出来的。安全相关的「差不多」通常等于「不行」。
第三,无状态令牌和权限变更之间有延迟。用户被降权后,旧令牌在过期前仍然带着旧权限;如果业务不能接受这个窗口,就要么缩短有效期,要么在每个请求里查一次用户状态。这个选择没有免费的解,只有在「查库次数」和「失效延迟」之间取舍。
第四,登录接口本身也要防暴力破解。本文只做了用户名密码相等判断,没有限流、没有失败计数、没有验证码。真实项目至少要有按 IP 和按用户的限流,密码要存哈希而不是明文。限流可以放在最外层中间件,具体实现第 6 篇部署时会提到反向代理层的位置。
第五,多实例部署时所有实例必须共享同一个密钥。如果每台机器启动时各自随机生成,负载均衡把请求分到另一台,令牌就验不过,表现为「时好时坏,刷新几次又能进」。密钥从统一的配置源注入,轮换时按上面的双密钥方案同步切换,别让实例之间出现版本差。
最后,令牌的传输必须依赖 HTTPS。明文 HTTP 下,Authorization 头和查询串一样会被中间人看到。本机用 127.0.0.1 调试可以接受,上线必须由反向代理终止 TLS,并且把 HTTP 请求重定向到 HTTPS。证书和 Nginx 配置的实际运行我没有在本机实测。
当天能自己验证的练习
- 用固定的
APP_SECRET调登录接口,记录返回的 token;重启服务但不换密钥,确认旧 token 仍然可用;再换一个密钥重启,确认旧 token 返回bad token。 - 把 token 的最后一位改掉、把用户名改成
admin再拼上原签名,分别请求/api/me,确认都返回 401,理解签名覆盖的范围。 - 把
Authorization的值改成bearer小写、去掉 Bearer 后的空格、只传 token 本身,记录三种情况分别返回no token还是bad token。 - 把 token 拼进查询串,请求后查看服务端日志和浏览器历史,确认它确实会被记录;再改回头部,确认日志里不再出现完整令牌。
- 给令牌加一个
exp字段并纳入签名,构造一个过期时间已到的 token,确认校验返回 401;再把exp改晚但不改签名,确认仍然失败。
身份解决之后,下一篇处理「请求之外的工作」。发邮件、生成报表、清理临时文件这些操作不该让用户等,也不该在请求线程里同步做完。后台任务那一篇会讲 tokio::spawn 的边界、阻塞调用为什么会把整个 worker 卡住,以及什么时候必须上独立队列。实测的任务日志也会放进去。
小结
三句话收束:令牌放 Authorization: Bearer,不要放查询串或无签名 cookie;签名要覆盖用户名、过期时间等所有可信字段,校验必须重新计算并比较;无状态令牌的代价是吊销困难,用短有效期、版本号或黑名单补,密钥从环境变量来。
这一篇的 AuthUser 提取器可以直接留在工程里,后面加后台任务接口时,用同一个提取器就能知道「是谁发起的任务」,不需要再解析一遍令牌。