一个运营后台的登录令牌存在 localStorage 里,前端每次请求手动加到 Authorization 头。某天客服收到一封用户反馈,点开一个「订单详情」链接后,账号出现了不是自己操作的发货记录。排查发现那个页面被注入了一段脚本,脚本读出 localStorage 里的令牌,发到外部服务器。令牌没有过期,攻击者拿着它可以直接调用接口,服务端完全看不出区别。
第二个问题更常见:用户点了退出登录,前端清掉了本地令牌,但服务端没有做任何失效处理。有人把退出前抓到的令牌重新放回去,接口依旧返回 200。这不是前端没清干净,而是 JWT 本身是无状态的,签发出去之后,服务端默认没有「作废」这个概念。
第三个问题藏得更深:页面上的「删除」按钮只对管理员显示,前端根据登录接口返回的 role 判断。有人用普通账号登录,改掉前端状态,按钮出现了,请求也发出去了,服务端照样执行删除,因为它从没检查过角色。这篇把「你是谁」和「你能做什么」分开讲:先比较会话的两种载体,再落到 Cookie 属性、JWT 签发校验、鉴权中间件和资源归属判断,最后说明 401 和 403 的排查方向为什么完全不同。
会话的两种载体:服务端状态与自包含令牌
会话要解决的问题是:用户登录一次之后,后续请求怎么证明「还是这个人」。有两种基本做法。第一种是服务端保存会话记录,浏览器只拿一个随机 ID,每次请求带回来,服务端查记录。第二种是把身份信息签进一个令牌,服务端只验证签名,不查记录。JWT 就是第二种,全称是 JSON Web Token,本质是一段带签名的 JSON,不是加密。
| 维度 | Session Cookie | JWT |
|---|---|---|
| 状态存放 | 服务端内存、Redis 或数据库 | 客户端持有,服务端不存 |
| 吊销 | 删除会话记录立即生效 | 默认无法吊销,要额外维护黑名单或版本号 |
| 横向扩展 | 多副本需要共享存储或粘性会话 | 副本只需共享密钥 |
| 体积 | Cookie 里只有一个随机 ID | 每次请求都带完整声明,通常几百字节 |
| 内容可见性 | 客户端看不到会话内容 | 载荷只做 Base64URL 编码,任何人可解码 |
没有哪一种绝对更好,关键看业务更怕什么。需要「立刻踢下线」「按设备管理登录」的系统,session 更直接;无状态、多副本、跨服务调用的 API,JWT 更方便。很多团队最后选混合方案:短期 access token 用 JWT,长期 refresh token 存在服务端,退出时删掉 refresh 记录,access token 靠短有效期自然过期。
Cookie 属性与 CSRF:令牌放在哪里
如果令牌通过 Cookie 传输,三个属性决定了它的安全边界。HttpOnly 让 JavaScript 读不到这个 Cookie,XSS 脚本没法直接把令牌偷走;Secure 限制只在 HTTPS 下发送;SameSite 控制跨站请求是否携带 Cookie。SameSite=Lax 是多数浏览器的默认值,跨站的 POST 不带 Cookie,能挡住大部分 CSRF。
res.cookie('access_token', token, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
path: '/',
maxAge: 15 * 60 * 1000,
});
但 SameSite 不是完整的 CSRF 防御。它挡不住同站点的子域攻击,也挡不住某些老浏览器;如果业务需要跨站携带 Cookie,还得设 SameSite=None; Secure,等于主动放弃这层保护。这时要用 CSRF token:服务端下发一个随机值,前端在请求头里带回,攻击者的跨站表单无法读取这个值,也就伪造不了。
另一种做法是双提交 Cookie:把随机 token 同时写进一个非 HttpOnly 的 Cookie 和请求头,服务端比较两者是否一致。它不依赖服务端存储,适合无状态 API,但要求前端能读到那个 Cookie,不能把 HttpOnly 开在它身上。
如果令牌放在 localStorage,就完全暴露给 XSS。HttpOnly Cookie 能挡住「直接偷令牌」,但挡不住 XSS 用当前页面发起请求,因为浏览器会自动带上 Cookie。所以真正的防线还是不让 XSS 发生:输出转义、CSP、依赖审计,缺一不可。把令牌从 localStorage 挪到 HttpOnly Cookie 是降低损失,不是消灭风险。
用 jsonwebtoken 签发和校验
本篇示例的依赖有四个:Express 提供 HTTP 层,jsonwebtoken 负责签发校验,argon2 负责密码哈希,express-rate-limit 负责登录限流。它们都在 Node 24 下安装并运行过:
{
"name": "auth-lab",
"private": true,
"type": "module",
"scripts": {
"start": "node src/server.js"
},
"dependencies": {
"express": "^5.3.0",
"jsonwebtoken": "^9.0.3",
"argon2": "^0.45.2",
"express-rate-limit": "^8.0.0"
}
}
npm install express@5 jsonwebtoken@9 argon2 express-rate-limit
npm start
jsonwebtoken 是 Node 里最常用的 JWT 实现。签发时把用户标识、角色、签发方和过期时间写进载荷,用密钥签名;校验时验证签名、过期时间、签发方和算法。
下面这段在本机真实执行过:
import jwt from 'jsonwebtoken';
const secret = 'dev-only-secret-please-rotate';
const token = jwt.sign(
{ sub: '42', role: 'admin', tenant: 't1' },
secret,
{ algorithm: 'HS256', expiresIn: '1h', issuer: 'orders-api' }
);
const decoded = jwt.verify(token, secret, {
algorithms: ['HS256'],
issuer: 'orders-api',
});
console.log(decoded);
签发出的令牌形如 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsInJvbGUiOiJhZG1pbiIsInRlbmFudCI6InQxIiwiaWF0IjoxNzk0MDExNDM0LCJleHAiOjE3OTQwMTUwMzQsImlzcyI6Im9yZGVycy1hcGkifQ.Rj6p_BPiZqT2wGd7YmzXvaPwtJP4AgN-OU3m0UPoZXY。校验后的输出是:
{"sub":"42","role":"admin","tenant":"t1","iat":1794011434,"exp":1794015034,"iss":"orders-api"}
过期和篡改是两种不同的错误,必须分开处理。把 expiresIn 设为 -1s 后校验,真实结果是 TokenExpiredError: jwt expired;修改载荷但保留原签名,结果是 JsonWebTokenError: invalid signature。前者可以引导用户刷新令牌,后者说明令牌不可信,应该直接 401 并记录异常。
校验时一定要显式传 algorithms。不传的话,库会接受令牌头里声明的算法,历史上出现过把 alg 改成 none 或换成非对称算法的攻击。还要校验 issuer 和 audience,否则另一个系统签发的令牌也可能被本系统接受。
jwt.decode 判断权限。decode 只解码不验签,任何人都能改角色。服务端每次请求都必须 verify,客户端解码只用于显示,不能作为任何授权依据。requireAuth 中间件与 req.user
鉴权中间件的职责很窄:从请求里取出令牌、验证、把可信的身份信息挂到 req.user,然后交给后面的处理函数。它不查数据库、不判断具体权限,也不负责生成响应体。这样拆分后,同一段逻辑可以挂在单个路由、一个 Router 或全局。
function requireAuth(req, res, next) {
const header = req.headers.authorization || '';
const token = header.startsWith('Bearer ') ? header.slice(7) : '';
if (!token) return res.status(401).json({ error: 'missing_token' });
try {
req.user = jwt.verify(token, secret, {
algorithms: ['HS256'],
issuer: 'orders-api',
});
next();
} catch {
res.status(401).json({ error: 'invalid_token' });
}
}
真实接口的三种响应:
GET /me 带合法令牌
HTTP/1.1 200 OK
{"userId":"1","role":"admin"}
GET /me 不带令牌
HTTP/1.1 401 Unauthorized
{"error":"missing_token"}
GET /me 带伪造令牌
HTTP/1.1 401 Unauthorized
{"error":"invalid_token"}
注意 sub 是字符串,数据库里的用户 ID 可能是数字。比较时统一转换,否则 '1' !== 1 会让合法用户被判成越权。这个细节在「自己的资源却返回 403」的故障里非常常见。
中间件捕获错误时不要把 err.message 返回给客户端。过期和签名错误对外都应该是 401,具体原因写进日志和 WWW-Authenticate 头。客户端只需要知道「令牌不能用」,不需要知道是过期还是密钥不对。
401 与 403:认证和授权是两件事
401 表示「我不知道你是谁」,通常因为没带令牌、令牌过期、签名不对、密钥不匹配。403 表示「我知道你是谁,但你不能做这件事」,通常因为角色不够、资源不属于你、账号被禁用。把两者混用,会让前端无法决定是跳登录页还是提示无权限,也会让排查方向跑偏。
角色检查可以放在中间件里做粗粒度过滤,比如只有管理员能进 /admin 前缀。但真正决定「能不能删这条订单」的,是资源归属和业务状态,必须放在服务层,用当前用户 ID 和资源所属用户 ID 比较。
app.delete('/admin/users/:id', requireAuth, (req, res) => {
if (req.user.role !== 'admin') {
return res.status(403).json({ error: 'forbidden' });
}
res.status(204).end();
});
用普通成员令牌调用管理员接口,真实返回:
HTTP/1.1 403 Forbidden
{"error":"forbidden"}
资源归属的判断要更细。比如 GET /orders/:id,管理员可以看所有订单,普通用户只能看自己的。正确做法是先按 ID 查出订单,再判断 order.user_id 是否等于 req.user.sub,不匹配返回 404 而不是 403。返回 404 可以避免攻击者通过状态码枚举「哪些订单存在」,这是常见的接口安全习惯。
只在前端隐藏按钮不叫权限控制。前端代码可以被修改、接口可以被直接调用,服务端必须对每个敏感操作独立判断。把权限判断集中到一个策略函数,输入是「当前用户、动作、资源」,输出是允许或拒绝,比在每个路由里散落 if (role === 'admin') 更容易审计。
登录:argon2 与失败限流
密码不能明文存,也不该用 md5 或裸 sha256。推荐 Argon2id,它是专门为密码哈希设计的算法,默认参数会消耗内存和 CPU,让暴力破解变慢。argon2 包的 hash 和 verify 都是异步的,直接可用。
const hash = await argon2.hash('correct-horse');
await argon2.verify(hash, 'correct-horse');
HASH=$argon2id$v=19$m=65536,t=3,p=...
VERIFY=true
WRONG=false
哈希结果里带有算法和参数,验证时不需要你记住当初用了多少内存。升级参数后,老密码仍然能验证,可以在下次登录成功时用新参数重新哈希,逐步迁移。不要自己拼接盐,也不要比较哈希字符串是否相等,verify 会做常量时间比较。
登录接口必须限流。攻击者可以拿一个手机号或邮箱反复试密码,也可以撞库。限流要同时按 IP 和按账号维度做,只按 IP 会被代理池绕过,只按账号会误伤共享出口的用户。下面是最小配置,实测第三次请求返回 429:
import { rateLimit } from 'express-rate-limit';
app.use('/auth', rateLimit({
windowMs: 60 * 1000,
limit: 2,
standardHeaders: 'draft-8',
legacyHeaders: false,
message: { error: 'too_many_attempts' },
}));
HTTP/1.1 429 Too Many Requests
RateLimit: "2-in-1min"; r=0; t=60
{"error":"too_many_attempts"}
生产环境多副本时,内存计数器各自独立,实际额度会变成「副本数乘以 limit」。要么把计数放到 Redis,要么接受这个近似值并在网关层再做一层限制。限流不是越严越好,登录成功后的正常操作不该被误伤,阈值要按真实流量调。
刷新、轮换与吊销
access token 的有效期应该短,十五分钟到一小时,减少泄露后的可用窗口。但短到用户频繁重新登录也不行,所以配一个 refresh token:有效期长,存在服务端,只能用来换新的 access token。刷新时旧 refresh 立即作废,发一个新的,这叫轮换。
轮换的关键是「重复使用检测」。如果同一个 refresh token 被用了两次,说明它可能被复制:第一次是攻击者,第二次是真实用户,或者反过来。服务端应该把这一整条刷新链作废,强制重新登录,而不是只拒绝第二次。
JWT 的吊销没有免费方案。可选做法有三种:维护一个黑名单,记录已吊销的令牌 ID,每次校验都查;给用户表加一个 token_version,签发时写进载荷,校验时和数据库比对,改版本号即全部失效;或者干脆把 access token 缩短到五分钟,接受「最多五分钟的延迟吊销」。黑名单要存到 Redis 或数据库,查一次就是一次 IO;版本号方案每次请求也要查用户,和有状态会话差别不大。
kid 标识密钥,服务端同时保留新旧两把,签发用新密钥,校验按 kid 选密钥。等所有旧 access token 都过期后,再删除旧密钥。直接换密钥会让所有在线用户瞬间 401。NestJS 的 Guard 与 @Roles
NestJS 11 把鉴权拆成 Guard,它在一个请求进入控制器之前执行,能读到路由元数据。典型写法是 @UseGuards(JwtAuthGuard, RolesGuard) 配合 @Roles('admin'),RolesGuard 用 Reflector 取出装饰器写入的角色列表,再和 request.user 比较。
Express 的鉴权是中间件
顺序由 app.use 和路由参数决定,鉴权逻辑是一个普通函数。粒度靠挂载点控制,简单直接,但角色和资源的判断容易散落在各个处理函数里。
NestJS 的鉴权是 Guard
Guard 在 Pipe 和控制器之前执行,能通过装饰器声明所需角色,拒绝时抛 ForbiddenException。结构统一,但要多理解一层元数据和依赖注入。资源归属仍然要在 Service 里判断,Guard 只适合粗粒度。
两者的共同点是:认证解决「是谁」,授权解决「能做什么」,资源归属必须在业务层判断。换框架不会自动带来安全的权限模型,只是换了写判断的位置。
现象、真实原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 浏览器 401,curl 却 200 | 前端没带 Authorization,或代理丢掉了请求头 | 看浏览器请求头和反向代理配置,确认 Bearer 前缀 |
| 发布后全员突然 401 | 多副本密钥不一致,或轮换了密钥但旧令牌未过期 | 对比各副本环境变量,确认 JWT_SECRET 同源且长度足够 |
| 登录后十几分钟就 401 | access token 过期,前端没有刷新流程 | 看 exp 和响应头,补 refresh 逻辑或延长有效期 |
| 退出登录后旧令牌仍能用 | JWT 无状态,服务端没有吊销机制 | 确认是否有黑名单或 token_version,检查退出接口是否真的写了失效记录 |
| 已登录但操作返回 403 | 角色不足,或资源归属判断用了错误的用户 ID | 打印 req.user.sub 与资源所有者,确认类型和来源 |
| 管理员账号也 403 | 角色声明过期,数据库里已改角色但令牌没刷新 | 对比令牌里的 role 与数据库当前值,必要时强制刷新 |
| 跨域请求带不上 Cookie | SameSite 或 Secure 配置与访问方式不匹配 | 看响应的 Set-Cookie 属性,确认前端 credentials 设置 |
| 登录接口被刷爆 | 没有限流,或限流只按 IP 且被代理池绕过 | 看 429 比例和账号维度计数,确认限流存储是否共享 |
边界与代价
JWT 的无状态是优点也是代价。它让副本扩展变简单,却把吊销变成了额外工程:黑名单要存、要查、要清理,版本号要每次比对,最终还是要依赖一个共享存储。如果业务每天都要踢人下线、按设备管理会话,直接用服务端会话可能更省事,别为了「无状态」三个字背上更复杂的补偿逻辑。
把令牌放 Cookie 能挡住直接读取,但会引入 CSRF;放 localStorage 能避开 CSRF,却把令牌交给 XSS。两者都不是绝对安全,真正的选择是「你更愿意防哪一种攻击」以及「有没有能力把那种攻击防住」。无论选哪种,都要配合输出转义、CSP、依赖升级和最小权限。
权限模型的成本会随业务增长。角色少的时候,一个 role 字段够用;出现「同一角色在不同租户权限不同」「资源级共享」「临时授权」之后,角色就撑不住了,需要权限表或策略引擎。提前设计太复杂会拖慢开发,完全不设计又会在权限补丁上反复返工。务实的做法是先把「认证」和「资源归属」做对,角色模型按真实需求演进。
密码哈希是有成本的。Argon2 消耗内存和 CPU,登录接口的吞吐会下降,这是故意的。不要为了压测数字把内存参数调到很低,那等于削弱暴力破解的成本。把登录和普通接口分开部署或限流,避免登录流量拖垮整个服务。
当天能自己验证的练习
- 用
jwt.sign签发一个expiresIn: '1h'的令牌,复制到jwt.verify里打印载荷;再把有效期改成'-1s',确认错误名是TokenExpiredError。 - 把令牌中间那段 Base64URL 解码,改掉
role后重新拼回去,调用校验,确认得到JsonWebTokenError: invalid signature。 - 用 argon2 哈希一个密码,分别用正确和错误密码调用
verify,记录true和false;观察哈希前缀里的m、t、p参数。 - 启动带
requireAuth的服务,分别请求不带令牌、带伪造令牌、带合法令牌的/me,记录 401、401、200 三种响应。 - 用管理员和普通成员分别调用管理员删除接口,确认 403 的分支;再把限流设为每分钟 2 次,连续请求三次,记录 429 和
RateLimit响应头。
小结
三句话:JWT 只证明「令牌未被篡改」,不证明「令牌仍然有效」,吊销要额外设计;Cookie 属性能降低 XSS 和 CSRF 的损失,但不能替代输出转义和服务端权限判断;401 查身份,403 查权限和资源归属,两者不要混用。
下一篇讲后台任务。鉴权解决了「谁能触发操作」,但很多操作不该在请求线程里做完,比如发券、生成报表、同步第三方数据。用 setInterval 跑定时任务,进程重启就丢;多副本同时跑,又会重复发券。下一篇会从这两个真实事故讲到 BullMQ 的队列、重试、重复任务和优雅停机。