JWT di Node.js: Sign, Verify dan Melindungi Route Express

JWT (JSON Web Token) adalah string berisi tiga bagian base64url, header.payload.signature, yang diberikan server kepada user saat login dan dicek di setiap request sesudahnya. Signature-nya membuktikan bahwa server yang menerbitkan token dan tidak ada yang mengubahnya, tetapi payload-nya hanya di-encode, tidak dienkripsi, jadi siapa pun bisa membacanya. Di Node.js kamu membuatnya dengan new SignJWT(payload).sign(secret) dari package jose dan mengeceknya dengan 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);

Hasilnya 3 parts, lalu user-42 admin: jwtVerify mengecek signature dan masa berlakunya lalu mengembalikan payload-nya. Ubah satu karakter dari secret yang diberikan ke jwtVerify lalu jalankan lagi: verifikasinya gagal dengan signature verification failed.

Apa isi sebuah JWT

Header dan payload-nya adalah JSON, di-encode dengan base64url. Men-decode-nya tidak butuh key, itulah sebabnya JWT tidak boleh berisi password atau hal rahasia lainnya.

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);

Dua baris pertama mencetak {"alg":"HS256"} dan {"name":"Ada","role":"editor"}, yang bisa dibaca siapa pun yang memegang token-nya. Signature-nya (43 karakter untuk HS256) yang mencegah mereka mengubahnya: ganti editor menjadi admin dan signature-nya tidak cocok lagi.

Masa berlaku dan verifikasi yang gagal

setExpirationTime('15m') menulis claim exp, dan jwtVerify menolak token yang sudah melewatinya. Setiap penolakan adalah error dengan code, jadi kamu bisa membedakan token yang kedaluwarsa dari token palsu.

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);
}

Pengecekan pertama gagal dengan ERR_JWT_EXPIRED dan yang kedua, yang signature-nya diubah, dengan ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Bagi API-mu keduanya berarti sama (jawab 401), tetapi mencatat kodenya membantu saat debugging.

Melindungi route Express dengan Bearer token

Client login sekali, menyimpan token-nya, lalu mengirimnya di header Authorization sebagai Bearer <token>. Sebuah middleware memverifikasinya dan menaruh payload-nya di req.user untuk route.

// 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 pertama, GET /me tanpa token, mendapat 401 dan Missing token. Kirim POST /login dengan body {"username": "ada", "password": "lovelace"}, salin token dari response-nya, lalu kirim GET /me lagi dengan header Authorization: Bearer <token>: jawabannya {"id":"user-1","name":"ada"}.

Package jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) adalah pilihan umum lainnya. sign dan verify miliknya synchronous (dengan callback opsional), bukan mengembalikan 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

Pakai jose untuk kode baru: package ini tidak punya dependency dan juga berjalan di edge runtime dan browser. Token dari kedua library adalah JWT standar, jadi yang satu bisa memverifikasi token yang ditandatangani yang lain.

Kesalahan umum

Memakai decode alih-alih verify. jwt.decode dan decodeJwt membaca payload tanpa mengecek signature-nya, jadi token palsu bisa lolos. Percayai hanya apa yang dikembalikan verify.

Secret yang pendek atau ikut di-commit. Secret HS256 yang bisa ditebak membuat penyerang bisa menandatangani token mereka sendiri. Pakai paling sedikit 32 byte acak, baca dari process.env, dan jangan pernah commit.

Token yang tidak pernah kedaluwarsa. Tanpa exp, token yang bocor berlaku selamanya. Selalu atur masa berlaku.