JWT ב-Node.js: חתימה, אימות והגנה על routes ב-Express

JWT ‏(JSON Web Token) הוא מחרוזת משלושה חלקים ב-base64url, ‏header.payload.signature, ששרת נותן למשתמש בהתחברות ובודק בכל בקשה מאוחרת יותר. החתימה מוכיחה שהשרת הנפיק את ה-token ושאף אחד לא שינה אותו, אבל ה-payload רק מקודד, לא מוצפן, כך שכל אחד יכול לקרוא אותו. ב-Node.js יוצרים אחד עם new SignJWT(payload).sign(secret) מהחבילה jose ובודקים אותו עם 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);

הוא מדפיס 3 parts, ואז user-42 admin: ‏jwtVerify בדק את החתימה ואת התוקף והחזיר את ה-payload. שנו תו אחד בסוד שמועבר ל-jwtVerify והריצו שוב: האימות נכשל עם signature verification failed.

מה יש בתוך JWT

ה-header וה-payload הם JSON, מקודדים ב-base64url. כדי לפענח אותם לא צריך מפתח, ובגלל זה JWT אף פעם לא צריך להחזיק סיסמה או כל דבר סודי אחר.

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

שתי השורות הראשונות מדפיסות {"alg":"HS256"} ו-{"name":"Ada","role":"editor"}, קריאים לכל מי שמחזיק את ה-token. החתימה (43 תווים ב-HS256) היא מה שמונע מהם לערוך אותו: שנו editor ל-admin והחתימה כבר לא תתאים.

תוקף ואימות שנכשל

setExpirationTime('15m') כותב claim בשם exp, ו-jwtVerify דוחה token שעבר אותו. כל דחייה היא שגיאה עם code, כך שאפשר להבדיל בין token שפג תוקפו לבין token מזויף.

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

הבדיקה הראשונה נכשלת עם ERR_JWT_EXPIRED והשנייה, שהחתימה שלה שונתה, עם ERR_JWS_SIGNATURE_VERIFICATION_FAILED. לגבי ה-API שלכם שתיהן אומרות אותו דבר (ענו 401), אבל רישום הקוד ללוג עוזר בדיבאג.

הגנה על route ב-Express עם Bearer token

הלקוח מתחבר פעם אחת, שומר את ה-token ושולח אותו ב-header ‏Authorization בתור Bearer <token>. middleware מאמת אותו ושם את ה-payload ב-req.user בשביל ה-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);

הבקשה הראשונה, GET /me בלי token, מקבלת 401 ו-Missing token. שלחו POST /login עם הגוף {"username": "ada", "password": "lovelace"}, העתיקו את ה-token מהתשובה, ואז שלחו שוב GET /me עם ה-header ‏Authorization: Bearer <token>: התשובה היא {"id":"user-1","name":"ada"}.

החבילה jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) היא הבחירה הנפוצה השנייה. ה-sign וה-verify שלה סינכרוניים (עם callbacks אופציונליים) במקום להחזיר promises:

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

השתמשו ב-jose בקוד חדש: אין לה תלויות, והיא רצה גם ב-edge runtimes ובדפדפנים. tokens משתי הספריות הם JWTs סטנדרטיים, כך שאחת יכולה לאמת את מה שהשנייה חתמה.

טעויות נפוצות

שימוש ב-decode במקום ב-verify. jwt.decode ו-decodeJwt קוראים את ה-payload בלי לבדוק את החתימה, כך ש-token מזויף עובר. סמכו רק על מה ש-verify מחזיר.

סוד קצר או סוד שעשו לו commit. סוד HS256 שאפשר לנחש מאפשר לתוקפים לחתום tokens משלהם. השתמשו לפחות ב-32 בייטים אקראיים, קראו אותם מ-process.env, ואל תעשו להם commit אף פעם.

tokens שלא פגים אף פעם. בלי exp, ‏token שדלף עובד לנצח. תמיד הגדירו תפוגה.