Autentikasi JWT & Refresh Token Rotation di Node.js: Cookie HttpOnly, Revokasi, & Deteksi Reuse
Mengimplementasikan JSON Web Token (JWT) hanya dengan membuat satu endpoint /login lalu menyimpan token berumur 30 hari di localStorage masih sangat umum dijumpai, tetapi menyimpan dua celah kritis. Pertama, jika ada satu titik kelengahan XSS di aplikasi frontend, skrip penyerang langsung bisa membaca localStorage dan mencuri akses akun selama berbulan-bulan. Kedua, karena JWT murni bersifat stateless, admin tidak punya cara mudah mencabut token yang telanjur bocor sebelum masa berlakunya habis.
Melengkapi pembahasan keamanan di panduan keamanan Node.js serta pola error terpusat pada arsitektur REST API Express.js, panduan ini membangun sistem autentikasi modern memadukan Access Token berumur pendek, cookie HttpOnly, serta Refresh Token Rotation dengan deteksi pemakaian ulang (reuse detection).
Arsitektur Dua Token yang Seimbang antara Keamanan & Performa
Alih-alih mengandalkan satu token raksasa berumur panjang, pisahkan tanggung jawab menjadi dua jenis token:
- Access Token (JWT, umur 10–15 menit): Disimpan di variabel memori JavaScript (bukan
localStorage) dan dikirim lewat headerAuthorization: Bearer .... Karena berumur sangat singkat, risiko kebocoran dibatasi dalam jendela menit. - Refresh Token (string acak kriptografis 48 byte, umur 7–14 hari): Disimpan di database dalam bentuk hash SHA-256 dan dikirim ke browser melalui cookie bertanda
HttpOnly; Secure; SameSite=Lax, sehingga sama sekali tidak dapat diakses lewatdocument.cookie.

Mengapa Refresh Token Harus di-Hash Sebelum Disimpan ke Database
Bila penyerang suatu saat berhasil membaca tabel refresh_tokens melalui celah SQL Injection atau kebocoran cadangan basis data, menyimpan token dalam teks polos berarti seluruh sesi pengguna langsung dapat diambil alih. Karena refresh token dibuat dari angka acak berentropi tinggi (crypto.randomBytes(48).toString('hex')), cukup hash nilainya memakai SHA-256 (crypto.createHash('sha256')) sebelum disimpan—tanpa membutuhkan algoritma lambat seperti bcrypt untuk token panjang acak.
Implementasi Endpoint Refresh Token Rotation & Reuse Detection
Kunci utama token rotation adalah aturan sekali pakai: setiap kali klien memanggil POST /api/auth/refresh, token lama ditandai revoked_at = NOW() dan satu token baru diterbitkan dalam family_id yang sama. Jika suatu saat token yang sudah pernah ditandai hangus dikirim kembali ke server, sistem mendeteksi bahwa salah satu pihak (pengguna asli atau pencuri token) memakai token kadaluarsa, lalu mencabut seluruh sesi dalam family_id tersebut:
// services/tokenRotation.mjs
import crypto from 'node:crypto';
import jwt from 'jsonwebtoken';
import { AppError } from '../errors/AppError.js';
export function hashToken(rawToken) {
return crypto.createHash('sha256').update(rawToken).digest('hex');
}
export function signAccessToken(user) {
return jwt.sign(
{ sub: user.id, role: user.role },
process.env.JWT_ACCESS_SECRET,
{ expiresIn: '15m', algorithm: 'HS256' }
);
}
export function setRefreshCookie(res, rawRefreshToken) {
res.cookie('refresh_token', rawRefreshToken, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
path: '/api/auth', // Hanya dikirim ke endpoint auth, tidak ikut di setiap asset/route
maxAge: 7 * 24 * 60 * 60 * 1000,
});
}
export async function rotateRefreshToken(db, rawCookieToken) {
if (!rawCookieToken) {
throw new AppError('Refresh token tidak ditemukan.', 401);
}
const tokenHash = hashToken(rawCookieToken);
const record = await db.refreshTokens.findByHash(tokenHash);
if (!record) {
throw new AppError('Sesi tidak valid.', 401);
}
// DETEKSI REUSE: Token ini sudah pernah dipakai & dirotasi sebelumnya!
if (record.revokedAt !== null) {
await db.refreshTokens.revokeAllByFamily(record.familyId);
throw new AppError('Aktivitas sesi mencurigakan terdeteksi. Silakan login ulang.', 401);
}
if (new Date(record.expiresAt) <= new Date()) {
throw new AppError('Sesi kedaluwarsa. Silakan login kembali.', 401);
}
const nextRawToken = crypto.randomBytes(48).toString('hex');
const nextHash = hashToken(nextRawToken);
const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
// Jalankan dalam transaksi database agar atomik
await db.transaction(async (trx) => {
await trx.refreshTokens.markRevoked(record.id);
await trx.refreshTokens.create({
userId: record.userId,
familyId: record.familyId,
tokenHash: nextHash,
expiresAt,
});
});
const user = await db.users.findById(record.userId);
return {
accessToken: signAccessToken(user),
rawRefreshToken: nextRawToken,
};
}
Perhatikan opsi path: '/api/auth' pada pengaturan cookie di atas. Menyetel path khusus ke awalan rute autentikasi membuat cookie sensitif tersebut tidak ikut dikirim pada permintaan ke endpoint gambar, analitik, atau API lain yang tidak memerlukannya.
Endpoint Logout yang Benar-Benar Mematikan Sesi
Kesalahan klasik lain adalah membuat tombol logout yang hanya menghapus token di sisi klien tanpa memberi tahu server. Pada pola rotasi ini, endpoint POST /api/auth/logout mencabut family_id di database dan membersihkan cookie dari browser:
export async function logoutController(req, res) {
const rawToken = req.cookies?.refresh_token;
if (rawToken) {
const record = await db.refreshTokens.findByHash(hashToken(rawToken));
if (record) {
await db.refreshTokens.revokeAllByFamily(record.familyId);
}
}
res.clearCookie('refresh_token', {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
path: '/api/auth',
});
res.json({ success: true, message: 'Berhasil keluar dari sesi.' });
}
Perbandingan Pola Penyimpanan Token di Aplikasi Web
| Lokasi Penyimpanan | Risiko XSS | Risiko CSRF | Kelayakan Produksi |
|---|---|---|---|
localStorage |
Tinggi (bisa dibaca JS apa saja di halaman) | Rendah | Tidak disarankan untuk Refresh Token atau JWT berumur lama. |
Cookie Biasa (tanpa HttpOnly) |
Tinggi (dapat dibaca document.cookie) |
Perlu mitigasi SameSite / token |
Tidak aman untuk kredensial autentikasi. |
Access Token di Memori + Refresh Token di Cookie HttpOnly |
Minimal (Refresh Token terisolasi dari JS) | Terkendali dengan SameSite=Lax & validasi Origin |
Pola standar industri yang mendukung revokasi dan pencabutan sesi instan. |
Tips tambahan untuk antarmuka frontend: jika beberapa permintaan API bersamaan sama-sama menerima 401 Expired pada milidetik yang sama, pastikan klien menampung satu promise refresh aktif secara terpusat (single-flight refresh) agar browser tidak mengirim tiga permintaan /auth/refresh paralel yang justru memicu deteksi reuse pada dua permintaan terakhir.
Diskusi & Komentar
0Sampaikan pertanyaan teknis, masukan, atau feedback Anda seputar artikel ini.
Belum Ada Komentar
Jadilah pembaca pertama yang memulai diskusi menarik atau bertanya seputar materi artikel ini!