Node.js JWT ile Kimlik Doğrulama ve Express Route'ları

JWT (JSON Web Token), üç base64url parçadan oluşan bir string'dir: header.payload.signature. Sunucu onu login sırasında kullanıcıya verir ve sonraki her istekte kontrol eder. İmza, token'ı sunucunun verdiğini ve kimsenin değiştirmediğini kanıtlar; ama payload şifrelenmemiş, sadece encode edilmiştir, yani herkes okuyabilir. Node.js'te jose paketindeki new SignJWT(payload).sign(secret) ile bir token oluşturur ve jwtVerify(token, secret) ile kontrol edersin.

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

Program 3 parts, ardından user-42 admin yazdırır: jwtVerify imzayı ve süreyi kontrol edip payload'u döndürdü. jwtVerify'a verilen secret'ın bir karakterini değiştirip tekrar çalıştır: doğrulama signature verification failed ile başarısız olur.

Bir JWT'nin içinde ne var

Header ve payload, base64url ile encode edilmiş JSON'dur. Onları decode etmek için anahtar gerekmez; bir JWT'nin asla parola ya da başka gizli bir şey taşımaması gerekmesinin nedeni budur.

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

İlk iki satır {"alg":"HS256"} ve {"name":"Ada","role":"editor"} yazdırır; token'ı elinde tutan herkes bunları okuyabilir. Onların token'ı düzenlemesini engelleyen imzadır (HS256 için 43 karakter): editor'ü admin yaparsan imza artık eşleşmez.

Süre dolması ve başarısız doğrulama

setExpirationTime('15m') bir exp claim'i yazar ve jwtVerify bu süreyi geçmiş bir token'ı reddeder. Her ret bir code taşıyan bir hatadır, böylece süresi dolmuş bir token'ı sahte olandan ayırt edebilirsin.

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

İlk kontrol ERR_JWT_EXPIRED ile, imzası değiştirilmiş ikincisi ise ERR_JWS_SIGNATURE_VERIFICATION_FAILED ile başarısız olur. API'n için ikisi de aynı anlama gelir (401 ile cevap ver), ama debug ederken kodu loglamak işe yarar.

Express route'unu Bearer token ile korumak

İstemci bir kez login olur, token'ı saklar ve onu Authorization header'ında Bearer <token> olarak gönderir. Bir middleware token'ı doğrular ve route için payload'u req.user'a koyar.

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

Token'sız ilk istek, GET /me, 401 ve Missing token alır. {"username": "ada", "password": "lovelace"} body'siyle POST /login gönder, cevaptaki token'ı kopyala, sonra GET /me'yi Authorization: Bearer <token> header'ıyla tekrar gönder: cevap {"id":"user-1","name":"ada"} olur.

jsonwebtoken paketi

jsonwebtoken (npm install jsonwebtoken) diğer yaygın seçenektir. sign ve verify fonksiyonları promise döndürmek yerine senkrondur (isteğe bağlı callback'lerle):

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

Yeni kod için jose kullan: hiç bağımlılığı yoktur ve edge runtime'larda ve tarayıcılarda da çalışır. İki kütüphanenin token'ları da standart JWT'dir, yani biri diğerinin imzaladığını doğrulayabilir.

Sık yapılan hatalar

verify yerine decode kullanmak. jwt.decode ve decodeJwt payload'u imzayı kontrol etmeden okur, bu yüzden sahte bir token geçer. Yalnızca verify'ın döndürdüğüne güven.

Kısa ya da commit edilmiş bir secret. Tahmin edilebilir bir HS256 secret'ı saldırganların kendi token'larını imzalamasına izin verir. En az 32 rastgele byte kullan, onu process.env'den oku ve asla commit etme.

Süresi hiç dolmayan token'lar. exp olmadan sızmış bir token sonsuza kadar çalışır. Her zaman bir süre ayarla.