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:3000

Windows 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 秒。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

登录与访问令牌

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通