JWT w Node.js: podpisywanie, weryfikacja i trasy Express

JWT (JSON Web Token) to string z trzech części w base64url, header.payload.signature, który serwer daje użytkownikowi przy logowaniu i sprawdza przy każdym kolejnym żądaniu. Podpis dowodzi, że token wydał serwer i nikt go nie zmienił, ale payload jest tylko zakodowany, a nie zaszyfrowany, więc każdy może go odczytać. W Node.js tworzysz go przez new SignJWT(payload).sign(secret) z pakietu jose i sprawdzasz przez 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);

Wypisuje 3 parts, a potem user-42 admin: jwtVerify sprawdził podpis i wygaśnięcie i zwrócił payload. Zmień o jeden znak sekret przekazany do jwtVerify i uruchom ponownie: weryfikacja kończy się błędem signature verification failed.

Co jest w środku JWT

Header i payload to JSON zakodowany w base64url. Dekodowanie nie wymaga klucza, dlatego JWT nigdy nie może zawierać hasła ani niczego innego tajnego.

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

Pierwsze dwie linie wypisują {"alg":"HS256"} i {"name":"Ada","role":"editor"}, czytelne dla każdego, kto ma token. Podpis (43 znaki dla HS256) sprawia, że nie da się go zmienić: zamień editor na admin, a podpis przestanie pasować.

Wygaśnięcie i nieudana weryfikacja

setExpirationTime('15m') zapisuje claim exp, a jwtVerify odrzuca token po tym czasie. Każde odrzucenie to błąd z code, więc odróżnisz wygasły token od podrobionego.

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

Pierwsze sprawdzenie kończy się błędem ERR_JWT_EXPIRED, a drugie, z podmienionym podpisem, błędem ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Dla twojego API oba znaczą to samo (odpowiedz 401), ale logowanie kodu pomaga przy debugowaniu.

Ochrona trasy Express tokenem Bearer

Klient loguje się raz, zachowuje token i wysyła go w nagłówku Authorization jako Bearer <token>. Middleware go weryfikuje i umieszcza payload w req.user dla trasy.

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

Pierwsze żądanie, GET /me bez tokena, dostaje 401 i Missing token. Wyślij POST /login z body {"username": "ada", "password": "lovelace"}, skopiuj token z odpowiedzi, a potem wyślij jeszcze raz GET /me z nagłówkiem Authorization: Bearer <token>: odpowiedź to {"id":"user-1","name":"ada"}.

Pakiet jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) to drugi popularny wybór. Jego sign i verify są synchroniczne (z opcjonalnymi callbackami), zamiast zwracać 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

W nowym kodzie używaj jose: nie ma zależności i działa też w środowiskach edge i przeglądarkach. Tokeny z obu bibliotek to standardowe JWT, więc jedna zweryfikuje to, co podpisała druga.

Częste błędy

Używanie decode zamiast verify. jwt.decode i decodeJwt czytają payload bez sprawdzania podpisu, więc podrobiony token przejdzie. Ufaj tylko temu, co zwraca verify.

Krótki albo zacommitowany sekret. Sekret HS256, który da się zgadnąć, pozwala atakującym podpisywać własne tokeny. Używaj co najmniej 32 losowych bajtów, czytaj je z process.env i nigdy ich nie commituj.

Tokeny, które nigdy nie wygasają. Bez exp wykradziony token działa w nieskończoność. Zawsze ustawiaj wygaśnięcie.