Toidicode.com

Toidicode.com

BASIC TO ADVANCE

Bài 20: Xác thực API bằng JWT trong Express

Ở bài trước MiniBlog đã có REST API, nhưng ai cũng tạo được bài viết qua POST /api/v1/posts. Tiếp tục với series, bài này mình sẽ giới thiệu với mọi người về xác thực API bằng JWT trong Express để chỉ tác giả đã đăng nhập mới tạo được bài.

1. JWT là gì?

JWT (JSON Web Token) là chuỗi ba phần header.payload.signature mã hoá base64url. Header ghi thuật toán ký (VD: HS256), payload chứa các claim như sub (user nào), iat (lúc tạo), exp (lúc hết hạn), signature là chữ ký tạo từ hai phần đầu và một secret chỉ server biết. Sửa một ký tự trong payload là chữ ký không còn khớp.

Luồng làm việc: client gửi email, mật khẩu để lấy một access token, rồi gắn nó vào header Authorization: Bearer <token> ở mỗi request. Server chỉ kiểm tra chữ ký và hạn, không tra session. Token lộ thì ai cũng dùng được tới khi hết hạn, nên access token phải sống ngắn: MiniBlog để 15 phút.

Mình dùng package jsonwebtoken (bản 9.0.3) và tạo secret bằng lệnh của Bài 15:

npm install jsonwebtoken
node -p "require('node:crypto').randomBytes(32).toString('hex')"

Các bạn thêm JWT_SECRET=<chuỗi vừa tạo> (khác SESSION_SECRET) vào .env, thêm JWT_SECRET= để trống vào .env.example như Bài 15, rồi khởi động lại server.

2. Tạo và kiểm tra token.

- lib/jwt.js

import jwt from 'jsonwebtoken';

const SECRET = process.env.JWT_SECRET;
const ALGORITHM = 'HS256';
export const EXPIRES_IN = 15 * 60; // 15 phút, tính bằng giây

// Thiếu secret, quá ngắn hoặc còn là chuỗi mẫu thì dừng ngay khi khởi động
if (!SECRET || SECRET.length < 32 || SECRET.startsWith('thay-bang')) {
    throw new Error('Biến môi trường JWT_SECRET phải là chuỗi ngẫu nhiên ít nhất 32 ký tự');
}

// Tạo access token cho user: sub là id của user, exp do expiresIn tính ra
export function signAccessToken(user) {
    return jwt.sign({}, SECRET, {
        algorithm: ALGORITHM,
        expiresIn: EXPIRES_IN,
        subject: String(user.id),
    });
}

// Kiểm tra chữ ký và hạn, sai thì ném lỗi; chỉ chấp nhận HS256
// maxAge: token không có exp cũng chỉ dùng được 15 phút kể từ iat
export function verifyAccessToken(token) {
    return jwt.verify(token, SECRET, { algorithms: [ALGORITHM], maxAge: EXPIRES_IN });
}

Trong đó:

  • jwt.sign() tự thêm iat, tính exp từ expiresIn, sub lấy từ subject (phải là chuỗi). Payload ai cũng đọc được, đừng để dữ liệu bí mật vào đó.
  • jwt.verify() trả về payload khi chữ ký đúng và chưa hết hạn, ngược lại ném TokenExpiredError hoặc JsonWebTokenError.
  • algorithms: ['HS256'] ghim thuật toán: token khai báo thuật toán khác trong header (kể cả none, không chữ ký) đều bị từ chối.
  • maxAge tính tuổi token từ iat: token thiếu exp cũng chỉ sống 15 phút.
  • Câu throw chạy ngay khi app.js import router API: thiếu JWT_SECRET, ngắn hơn 32 ký tự hay còn là chuỗi mẫu thì server không khởi động. Bài 23 sẽ kiểm tra mọi biến môi trường theo cách này.

3. API đăng nhập lấy token.

- controllers/api/auth-controller.js

import * as authService from '../../services/auth-service.js';
import * as loginAttempts from '../../lib/login-attempts.js';
import { signAccessToken, EXPIRES_IN } from '../../lib/jwt.js';
import HttpError from '../../lib/http-error.js';

// POST /api/v1/auth/token: đúng email và mật khẩu thì trả access token
export async function token(req, res) {
    const email = String(req.body?.email ?? '').trim().toLowerCase();
    const password = String(req.body?.password ?? '');
    // Bộ đếm đăng nhập sai dùng chung với form đăng nhập
    const key = loginAttempts.keyFor(email, req.ip);

    if (loginAttempts.isLocked(key)) {
        throw new HttpError(429, 'Bạn đã đăng nhập sai nhiều lần, vui lòng thử lại sau 15 phút');
    }
    const user = await authService.attempt(email, password);
    if (!user) {
        loginAttempts.recordFailure(key);
        throw new HttpError(401, 'Email hoặc mật khẩu không đúng');
    }
    loginAttempts.reset(key);

    res.json({
        data: { accessToken: signAccessToken(user), tokenType: 'Bearer', expiresIn: EXPIRES_IN },
    });
}

Controller dùng lại attempt() và bộ đếm loginAttempts của Bài 16 (5 lần sai thì khoá 15 phút), tính chung với form đăng nhập nên không lách được qua API. Sai email hay sai mật khẩu đều nhận cùng một thông báo 401.

4. Middleware xác thực Bearer.

- middlewares/api-auth.js

import HttpError from '../lib/http-error.js';
import { verifyAccessToken } from '../lib/jwt.js';
import { getUser } from '../services/auth-service.js';

// API cần đăng nhập: đọc header "Authorization: Bearer <token>", hợp lệ thì gán req.user
export async function requireToken(req, res, next) {
    const [scheme, token] = req.get('Authorization')?.split(' ') ?? [];
    let payload = null;
    if (scheme?.toLowerCase() === 'bearer' && token) {
        try {
            payload = verifyAccessToken(token);
        } catch {
            // Sai chữ ký, hết hạn hay hỏng định dạng đều báo chung một lỗi
        }
    }
    req.user = payload ? await getUser(Number(payload.sub)) : null;
    if (!req.user) {
        res.set('WWW-Authenticate', 'Bearer');
        throw new HttpError(401, 'Bạn cần đăng nhập bằng token hợp lệ');
    }
    next();
}

Kiểu Bearer không phân biệt hoa thường (RFC 7235) nên mình so sánh bằng toLowerCase(). Thiếu header, sai kiểu, token hỏng, hết hạn hay user đã bị xoá đều trả cùng một 401 kèm header WWW-Authenticate: Bearer. Lỗi ném trong hàm async được Express 5 chuyển cho error handler (Bài 7).

- routes/api-v1.js (đoạn thay đổi)

import * as authApi from '../controllers/api/auth-controller.js';
import { authLimiter } from '../middlewares/rate-limit.js';
import { requireToken } from '../middlewares/api-auth.js';

// ...
// Đăng nhập lấy token, dùng chung giới hạn request với form đăng nhập
router.post('/auth/token', authLimiter, authApi.token);

// Tạo bài cần token, kiểm tra token trước khi validate (validate có truy vấn DB)
router.post('/posts', requireToken, postRules, postApi.store);

authLimiter (Bài 17) là cùng một instance nên form và API đếm chung 10 request mỗi IP trong 15 phút. Trong store của controllers/api/post-controller.js, các bạn đổi lời gọi service thành createPost({ ...matchedData(req), authorId: req.user.id }): tác giả lấy từ token, client không tự khai được.

Router API vẫn mount trước csrfProtection như Bài 19. Bỏ qua CSRF an toàn vì trình duyệt không tự gắn header Authorization vào request từ trang khác; nếu chuyển token sang cookie thì phải bật lại kiểm tra CSRF.

5. Thử API với token.

Chạy npm run dev, dùng tài khoản [email protected] của Bài 16. Chưa có token thì bị từ chối:

curl -s -w ' %{http_code}\n' -H 'Content-Type: application/json' -d '{"title":"Xác thực API bằng JWT","content":"Bài viết này được tạo bằng access token."}' http://localhost:3000/api/v1/posts
# {"message":"Bạn cần đăng nhập bằng token hợp lệ"} 401
curl -s -w ' %{http_code}\n' -H 'Content-Type: application/json' -d '{"email":"[email protected]","password":"sai-mat-khau"}' http://localhost:3000/api/v1/auth/token
# {"message":"Email hoặc mật khẩu không đúng"} 401

Đăng nhập đúng thì nhận token, mình lưu vào biến TOKEN và xem payload:

curl -s -H 'Content-Type: application/json' -d '{"email":"[email protected]","password":"matkhau123"}' http://localhost:3000/api/v1/auth/token
# {"data":{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3OTQ3MjkwMzAsImV4cCI6MTc5NDcyOTkzMCwic3ViIjoiMSJ9.7wHT0C4fc5HBoQrocwUfdAMKNTQ2bSp-xDal7hEoxTw","tokenType":"Bearer","expiresIn":900}}
TOKEN=$(curl -s -H 'Content-Type: application/json' -d '{"email":"[email protected]","password":"matkhau123"}' http://localhost:3000/api/v1/auth/token | sed 's/.*"accessToken":"\([^"]*\)".*/\1/')
node -p "JSON.parse(Buffer.from(process.argv[1].split('.')[1], 'base64url'))" "$TOKEN"
# { iat: 1794729030, exp: 1794729930, sub: '1' }

exp hơn iat 900 giây. Có token thì bài được tạo, tác giả là user 1:

curl -s -i -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"title":"Xác thực API bằng JWT","content":"Bài viết này được tạo bằng access token."}' http://localhost:3000/api/v1/posts
# HTTP/1.1 201 Created
# ...
# {"data":{"id":3,"title":"Xác thực API bằng JWT","slug":"xac-thuc-api-bang-jwt","content":"Bài viết này được tạo bằng access token.","cover":null,"authorId":1,"publishedAt":"2026-11-15T07:50:31.000Z"}}
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer ${TOKEN}x" -H 'Content-Type: application/json' -d '{"title":"Token bị sửa","content":"Chữ ký của token đã bị sửa đổi."}' http://localhost:3000/api/v1/posts
# {"message":"Bạn cần đăng nhập bằng token hợp lệ"} 401

Lệnh thứ hai thêm một ký tự vào chữ ký nên bị từ chối. Quá 15 phút chạy lại lệnh đầu cũng nhận 401 đó, phải lấy token mới. Thử xong các bạn chạy npm run db:seed để xoá bài vừa tạo.

6. So sánh session và JWT.

  • Lưu ở đâu: session nằm ở server (bảng sessions), trình duyệt chỉ giữ session ID. JWT tự chứa thông tin, server không lưu gì.
  • Gửi lên thế nào: cookie do trình duyệt tự gửi nên cần chống CSRF. JWT do client gắn vào header, hợp với ứng dụng di động, frontend ở domain khác hay nhiều server.
  • Đăng xuất, thu hồi: xoá session là có hiệu lực ngay. JWT đã phát thì dùng được tới exp, muốn thu hồi sớm phải lưu danh sách đen ở server. Vì vậy access token phải ngắn hạn, thường đi kèm refresh token để người dùng không phải đăng nhập lại mỗi 15 phút.

MiniBlog giữ cả hai: trang web dùng session, API dùng JWT. Ở frontend nên giữ token trong bộ nhớ thay vì localStorage, nơi chỉ một lỗ hổng XSS là đủ để lấy cắp.

Code đầy đủ của MiniBlog sau bài này nằm ở tag bai-20 trên GitHub; các thay đổi của riêng bài này: so sánh bai-19...bai-20.

7. Lời kết.

Như vậy là chúng ta đã xác thực API bằng JWT trong Express: tạo và kiểm tra token với jsonwebtoken, API đăng nhập có giới hạn, middleware Bearer bảo vệ API tạo bài và hiểu khi nào nên dùng session hay JWT. Danh sách bài viết hiện vẫn trả về tất cả một lần, bài sau mình sẽ giới thiệu với mọi người về phân trang, tìm kiếm và lọc trong Express.

Đăng ký nhận tin.

Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!

Vũ Thanh Tài

About author
The best way to learn is to share
Xem tất cả bài đăng

0 Comments

Bài viết chưa có ai bình luận, hãy là người đầu tiên đi bạn!

Bình luận

Captcha