React / 系统课时
登录与访问令牌
登录与访问令牌
本课完成一个可运行的登录接口:服务端验证账号密码,成功后签发短期访问令牌,并明确令牌中该放什么、有效多久以及失败时如何返回安全的错误信息。
学习目标
- 理解账号验证、令牌签发与后续请求认证之间的关系
- 使用
bcryptjs校验密码并用 JWT 签发访问令牌 - 合理设计令牌声明、有效时间与登录失败响应
从账号验证到令牌签发
登录接口只负责证明“当前请求者掌握了正确凭证”,然后签发一个可在后续请求中携带的访问令牌。服务端不应把明文密码写入日志,也不应在“账号不存在”和“密码错误”之间返回不同提示,否则会帮助攻击者枚举有效账号。

成功后的访问令牌通常放在响应体中,由前端存储并通过 Authorization: Bearer <ACCESS_TOKEN> 发送。令牌只代表有限时间内的身份,不等同于永久登录状态。
设计令牌内容与有效时间
JWT 中适合放入稳定、最小且用于认证判断的信息,例如用户 ID、角色、签发方和目标受众。不要写入密码、手机号、身份证号等敏感信息,因为 JWT 默认只是签名而不是加密,持有者可以读取载荷。本例使用以下声明:
sub:用户唯一 ID,后续中间件据此识别用户role:演示用角色;真实项目中仍应以服务端权限数据为准iss与aud:限制令牌只能由指定服务签发并供指定客户端使用iat、exp与jti:记录签发时间、过期时间和令牌唯一标识
访问令牌设为 15 分钟。时间较短可以缩小令牌泄露后的风险窗口;需要长时间会话时,应另行设计刷新令牌,而不是把访问令牌直接改成数天有效。
实现登录接口
创建项目并安装依赖:
bash
npm init -y
npm install express bcryptjs jsonwebtoken
npm install -D typescript tsx @types/express @types/jsonwebtoken @types/node预期结果:
text
依赖安装完成,命令退出码为 0;实际安装包数量可能因版本不同而变化。新建 server.ts:
ts
import { randomUUID } from "node:crypto";
import express from "express";
import bcrypt from "bcryptjs";
import jwt from "jsonwebtoken";
const app = express();
app.use(express.json());
const PORT = 3000;
const JWT_SECRET =
process.env.JWT_SECRET ?? "dev-only-secret-change-me";
async function main(): Promise<void> {
// 仅用于本地演示;真实项目应从数据库读取密码哈希。
const demoUser = {
id: "u_1001",
username: "alice",
passwordHash: await bcrypt.hash("Passw0rd!", 10),
role: "USER",
};
app.post("/api/auth/login", async (req, res) => {
const { username, password } = req.body as {
username?: string;
password?: string;
};
const usernameMatched = username === demoUser.username;
const passwordMatched =
usernameMatched &&
typeof password === "string" &&
(await bcrypt.compare(password, demoUser.passwordHash));
if (!passwordMatched) {
return res.status(401).json({
code: "INVALID_CREDENTIALS",
message: "账号或密码错误",
});
}
// 令牌只保存最小身份信息,并同时限制签发方、受众和过期时间。
const accessToken = jwt.sign(
{ role: demoUser.role },
JWT_SECRET,
{
algorithm: "HS256",
subject: demoUser.id,
issuer: "react18-fullstack-api",
audience: "react18-fullstack-web",
expiresIn: 15 * 60,
jwtid: randomUUID(),
},
);
return res.json({
tokenType: "Bearer",
accessToken,
expiresInSeconds: 900,
});
});
app.listen(PORT, () => {
console.log(`API listening on http://localhost:${PORT}`);
});
}
main().catch((error: unknown) => {
console.error(error);
process.exit(1);
});运行服务:
bash
JWT_SECRET="replace-with-a-long-random-secret" npx tsx server.ts预期输出:
text
API listening on http://localhost:3000Windows PowerShell 可先执行 $env:JWT_SECRET="replace-with-a-long-random-secret",再运行 npx tsx server.ts。生产环境必须从密钥管理系统或环境变量读取高强度密钥,不能使用示例默认值。
调用接口并验证结果
发送正确凭证:
bash
curl -i -X POST http://localhost:3000/api/auth/login -H "Content-Type: application/json" -d '{"username":"alice","password":"Passw0rd!"}'预期结果:
text
HTTP/1.1 200 OK
{"tokenType":"Bearer","accessToken":"<ACCESS_TOKEN>","expiresInSeconds":900}<ACCESS_TOKEN> 每次签发都会不同,因为令牌包含时间与唯一标识。把密码改错后,接口应返回:
text
HTTP/1.1 401 Unauthorized
{"code":"INVALID_CREDENTIALS","message":"账号或密码错误"}验收时还应确认响应中没有密码哈希、密钥或多余用户隐私字段,并检查令牌的 exp - iat 约为 900 秒。
按自己的节奏,确认真正理解。