JWT trong Node.js: ký, xác thực và bảo vệ route Express

JWT (JSON Web Token) là một chuỗi gồm ba phần base64url, header.payload.signature, được server cấp cho người dùng khi đăng nhập và kiểm tra ở mọi request sau đó. Chữ ký chứng minh rằng server đã cấp token và không ai sửa nó, nhưng payload chỉ được mã hóa base64url chứ không được mã hóa bảo mật, nên ai cũng đọc được. Trong Node.js, bạn tạo token bằng new SignJWT(payload).sign(secret) từ package jose và kiểm tra nó bằng jwtVerify(token, secret).

import { SignJWT, jwtVerify } from 'jose';

// In a real app the secret comes from process.env.JWT_SECRET
const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');

const token = await new SignJWT({ role: 'admin' })
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject('user-42')
    .setIssuedAt()
    .setExpirationTime('1h')
    .sign(secret);

console.log(token.split('.').length, 'parts');

const { payload } = await jwtVerify(token, secret);
console.log(payload.sub, payload.role);

Chương trình in ra 3 parts, rồi user-42 admin: jwtVerify đã kiểm tra chữ ký và thời hạn rồi trả về payload. Sửa một ký tự trong khóa bí mật truyền vào jwtVerify rồi chạy lại: việc xác thực thất bại với signature verification failed.

Bên trong một JWT có gì

Header và payload là JSON, được mã hóa bằng base64url. Giải mã chúng không cần khóa, vì vậy JWT tuyệt đối không được chứa mật khẩu hay bất kỳ thông tin bí mật nào.

import { SignJWT } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const token = await new SignJWT({ name: 'Ada', role: 'editor' })
    .setProtectedHeader({ alg: 'HS256' })
    .sign(secret);

const [header, payload, signature] = token.split('.');

console.log(Buffer.from(header, 'base64url').toString());
console.log(Buffer.from(payload, 'base64url').toString());
console.log(signature.length);

Hai dòng đầu in ra {"alg":"HS256"} và {"name":"Ada","role":"editor"}, ai có token cũng đọc được. Chữ ký (43 ký tự với HS256) là thứ ngăn họ chỉnh sửa token: đổi editor thành admin thì chữ ký không còn khớp.

Thời hạn và xác thực thất bại

setExpirationTime('15m') ghi một claim exp, và jwtVerify từ chối token đã quá hạn này. Mỗi lần từ chối là một lỗi có code, nên bạn phân biệt được token hết hạn với token giả mạo.

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const expired = await new SignJWT({ sub: 'user-42' })
    .setProtectedHeader({ alg: 'HS256' })
    .setExpirationTime(1700000000) // a moment in 2023, long past
    .sign(secret);

try {
    await jwtVerify(expired, secret);
} catch (err) {
    console.log(err.code);
}

const forged = expired.slice(0, -2) + 'xx';
try {
    await jwtVerify(forged, secret);
} catch (err) {
    console.log(err.code);
}

Lần kiểm tra đầu thất bại với ERR_JWT_EXPIRED, còn lần thứ hai, với chữ ký đã bị sửa, thất bại với ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Với API của bạn thì cả hai đều như nhau (trả về 401), nhưng ghi log mã lỗi sẽ giúp khi gỡ lỗi.

Bảo vệ route Express bằng Bearer token

Client đăng nhập một lần, giữ token và gửi nó trong header Authorization dưới dạng Bearer <token>. Một middleware xác thực token và gắn payload vào req.user cho route dùng.

// GET /me
import express from 'express';
import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const app = express();
app.use(express.json());

app.post('/login', async (req, res) => {
    const { username, password } = req.body ?? {};
    // A real app looks the user up and checks a hashed password
    if (username !== 'ada' || password !== 'lovelace') {
        return res.status(401).json({ error: 'Wrong username or password' });
    }
    const token = await new SignJWT({ name: username })
        .setProtectedHeader({ alg: 'HS256' })
        .setSubject('user-1')
        .setExpirationTime('15m')
        .sign(secret);
    res.json({ token });
});

async function requireAuth(req, res, next) {
    const header = req.get('authorization') ?? '';
    const token = header.startsWith('Bearer ') ? header.slice(7) : null;
    if (!token) return res.status(401).json({ error: 'Missing token' });
    try {
        const { payload } = await jwtVerify(token, secret);
        req.user = payload;
        next();
    } catch {
        res.status(401).json({ error: 'Invalid or expired token' });
    }
}

app.get('/me', requireAuth, (req, res) => {
    res.json({ id: req.user.sub, name: req.user.name });
});

app.listen(3000);

Request đầu tiên, GET /me không có token, nhận 401 và Missing token. Gửi POST /login với body {"username": "ada", "password": "lovelace"}, sao chép token từ response, rồi gửi lại GET /me với header Authorization: Bearer <token>: câu trả lời là {"id":"user-1","name":"ada"}.

Package jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) là lựa chọn phổ biến còn lại. Hàm sign và verify của nó chạy đồng bộ (có thể kèm callback) thay vì trả về promise:

const jwt = require('jsonwebtoken');

const token = jwt.sign({ role: 'admin' }, process.env.JWT_SECRET, {
    subject: 'user-42',
    expiresIn: '1h',
});

const payload = jwt.verify(token, process.env.JWT_SECRET); // throws if invalid

Hãy dùng jose cho code mới: nó không có dependency nào và còn chạy được trên edge runtime và trình duyệt. Token từ thư viện nào cũng là JWT chuẩn, nên thư viện này xác thực được token mà thư viện kia đã ký.

Lỗi thường gặp

Dùng decode thay vì verify. jwt.decode và decodeJwt đọc payload mà không kiểm tra chữ ký, nên token giả mạo vẫn lọt qua. Chỉ tin những gì verify trả về.

Khóa bí mật quá ngắn hoặc bị commit. Một khóa HS256 dễ đoán cho phép kẻ tấn công tự ký token. Hãy dùng ít nhất 32 byte ngẫu nhiên, đọc nó từ process.env, và không bao giờ commit nó.

Token không bao giờ hết hạn. Không có exp, một token bị lộ sẽ dùng được mãi mãi. Luôn đặt thời hạn.