JWT in Node.js: signieren, prüfen, Express-Routen schützen

Ein JWT (JSON Web Token) ist ein String aus drei base64url-Teilen, header.payload.signature, den ein Server einem Nutzer beim Login gibt und bei jeder späteren Anfrage prüft. Die Signatur beweist, dass der Server das Token ausgestellt hat und niemand es verändert hat, aber die Payload ist nur kodiert, nicht verschlüsselt, jeder kann sie also lesen. In Node.js erstellst du eines mit new SignJWT(payload).sign(secret) aus dem Paket jose und prüfst es mit 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);

Es gibt 3 parts aus, dann user-42 admin: jwtVerify hat Signatur und Ablauf geprüft und die Payload zurückgegeben. Ändere das an jwtVerify übergebene Secret um ein Zeichen und führ es noch einmal aus: Die Prüfung schlägt mit signature verification failed fehl.

Was in einem JWT steckt

Header und Payload sind JSON, kodiert mit base64url. Zum Dekodieren braucht man keinen Schlüssel, deshalb darf ein JWT nie ein Passwort oder etwas anderes Geheimes enthalten.

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

Die ersten beiden Zeilen geben {"alg":"HS256"} und {"name":"Ada","role":"editor"} aus, lesbar für jeden, der das Token hat. Die Signatur (43 Zeichen bei HS256) verhindert, dass jemand es verändert: Ändere editor in admin, und die Signatur passt nicht mehr.

Ablauf und fehlgeschlagene Prüfung

setExpirationTime('15m') schreibt einen exp-Claim, und jwtVerify lehnt ein Token danach ab. Jede Ablehnung ist ein Fehler mit einem code, du kannst also ein abgelaufenes Token von einem gefälschten unterscheiden.

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

Die erste Prüfung schlägt mit ERR_JWT_EXPIRED fehl, die zweite, deren Signatur verändert wurde, mit ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Für deine API bedeuten beide dasselbe (antworte mit 401), aber den Code zu loggen hilft beim Debuggen.

Eine Express-Route mit einem Bearer-Token schützen

Der Client meldet sich einmal an, behält das Token und schickt es im Header Authorization als Bearer <token>. Eine Middleware prüft es und legt die Payload für die Route in req.user.

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

Die erste Anfrage, GET /me ohne Token, bekommt 401 und Missing token. Sende POST /login mit dem Body {"username": "ada", "password": "lovelace"}, kopier das token aus der Antwort und sende dann noch einmal GET /me mit dem Header Authorization: Bearer <token>: Die Antwort ist {"id":"user-1","name":"ada"}.

Das Paket jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) ist die andere verbreitete Wahl. Seine Funktionen sign und verify sind synchron (mit optionalen Callbacks), statt Promises zurückzugeben:

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

Nimm für neuen Code jose: Es hat keine Abhängigkeiten und läuft auch in Edge-Runtimes und Browsern. Tokens beider Bibliotheken sind Standard-JWTs, die eine kann also prüfen, was die andere signiert hat.

Häufige Fehler

decode statt verify verwenden. jwt.decode und decodeJwt lesen die Payload, ohne die Signatur zu prüfen, ein gefälschtes Token geht also durch. Vertrau nur dem, was verify zurückgibt.

Ein kurzes oder eingechecktes Secret. Ein erratbares HS256-Secret lässt Angreifer eigene Tokens signieren. Nimm mindestens 32 zufällige Bytes, lies sie aus process.env und committe sie nie.

Tokens, die nie ablaufen. Ohne exp funktioniert ein geleaktes Token für immer. Setz immer einen Ablauf.