JWT Doğrularken Yapılan Beş Hata ve Doğru Doğrulama

Kararı token değil sunucu verir

Diyelim ki bir API'nin erişim loglarında tuhaf bir istek gördünüz. Authorization başlığındaki token'ın son parçası boş, payload'da "rol":"admin" yazıyor ve sunucu isteğe 200 dönmüş. Kimse anahtarınızı çalmadı. Doğrulama kodu token'a ne yapması gerektiğini sordu, token da cevap verdi.

JWT hatalarının neredeyse hepsi bu kökten çıkar: doğrulayıcı kararı saldırganın yazdığı alanlara bırakır. Aşağıda beş yaygın hatayı Node üzerinde yerelde tetikleyip her birini kapatan doğrulayıcıyı kuracağız. Örnekler jsonwebtoken 9.0.0 ve jose 4.14.4 ile Node 20'de çalıştı.

decode ile verify aynı şey değil

JWT üç parçadan oluşur: header, payload ve imza. İlk ikisi JSON'un base64url ile yazılmış hâlidir. Base64url şifreleme değil, URL'de sorun çıkarmasın diye + ve / yerine - ve _ kullanan, padding'siz bir Base64 türü. Bir token'ı JWT Decoder aracına yapıştırdığınızda ya da ortadaki parçayı Base64 Kodlama ve Çözme aracından geçirdiğinizde içeriği anahtarsız görürsünüz. Aynı şeyi Node'da deneyelim, üstüne payload'u da kurcalayalım.

1// 01-decode.js2const jwt = require('jsonwebtoken');3 4const token = jwt.sign(5  { sub: '42', rol: 'kullanici', tckn: '12345678901' },6  'cok-gizli-bir-anahtar-en-az-32-bayt!!',7  { algorithm: 'HS256', expiresIn: '15m' }8);9 10// İmzayı bilmeden payload'u okumak için kütüphane bile gerekmiyor11const [, payload] = token.split('.');12console.log(Buffer.from(payload, 'base64url').toString());13 14// Payload'u değiştirip imzayı olduğu gibi bırakalım15const sahte = JSON.parse(Buffer.from(payload, 'base64url'));16sahte.rol = 'admin';17const [h, , s] = token.split('.');18const kurcalanmis = [h, Buffer.from(JSON.stringify(sahte)).toString('base64url'), s].join('.');19 20console.log('decode:', jwt.decode(kurcalanmis).rol);21try {22  jwt.verify(kurcalanmis, 'cok-gizli-bir-anahtar-en-az-32-bayt!!', { algorithms: ['HS256'] });23} catch (e) {24  console.log('verify:', e.message);25}

1$ node 01-decode.js2{"sub":"42","rol":"kullanici","tckn":"12345678901","iat":1687900080,"exp":1687900980}3decode: admin4verify: invalid signature

jwt.decode kurcalanmış token'dan admin döndürdü, çünkü decode yalnızca metni çözer. İmzayı kontrol eden verify'dır. Yetki kararını decode çıktısıyla verdiğiniz her satır, token'ı elle yazan herkese açık bir kapıdır. decode'un meşru bir kullanımı var: doğrulamadan önce header'daki kid alanını okuyup hangi anahtarla doğrulayacağınızı seçmek. O da üçüncü hatanın konusu.

Çıktının ilk satırı ikinci bir ders veriyor. tckn alanını token'ın uğradığı her yer görür: tarayıcı geçmişi, proxy logları, hata izleme servisleri, destek ekibine atılan ekran görüntüleri. JWT'ye kimlik numarası, e-posta ya da iç sistemlere ait ayrıntı koymayın. İçerik gerçekten gizli kalmalıysa JWE (şifreli JWT) diye ayrı bir biçim var. Ben önce payload'u küçültmeyi denerim: bir sub, gereken birkaç claim ve o kadar.

1. alg: none kabul etmek

RFC 7519, imzası olmayan JWT'ye izin verir. Bütünlüğün başka bir katmanda sağlandığı durumlar için tanımlanmış bu biçimde header "alg":"none" der ve üçüncü parça boştur. Header'ı okuyup ona göre davranan bir doğrulayıcı, token'ı imzası olmadığı için kontrol etmeden geçirir. Tim McLean 2015'te bazı JWT kütüphanelerinin tam olarak bunu yaptığını gösterdi. Hatayı görmek için bilerek naif bir doğrulayıcı yazalım.

1// 02-naif.js2const crypto = require('crypto');3 4const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');5 6// Naif doğrulayıcı: algoritmayı token'ın kendisinden okuyor7function naifVerify(token, anahtar) {8  const [h, p, s] = token.split('.');9  const header = JSON.parse(Buffer.from(h, 'base64url'));10 11  if (header.alg === 'none') {12    return JSON.parse(Buffer.from(p, 'base64url')); // imza yok, sorun yok (!)13  }14  if (header.alg === 'HS256') {15    const beklenen = crypto.createHmac('sha256', anahtar).update(`${h}.${p}`).digest('base64url');16    if (beklenen !== s) throw new Error('imza geçersiz');17  } else if (header.alg === 'RS256') {18    const ok = crypto.verify('sha256', Buffer.from(`${h}.${p}`), anahtar, Buffer.from(s, 'base64url'));19    if (!ok) throw new Error('imza geçersiz');20  } else {21    throw new Error('desteklenmeyen alg');22  }23  return JSON.parse(Buffer.from(p, 'base64url'));24}25 26const { publicKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });27const pem = publicKey.export({ type: 'spki', format: 'pem' });28 29// Saldırı 1: alg none30const none = `${b64({ alg: 'none', typ: 'JWT' })}.${b64({ sub: '1', rol: 'admin' })}.`;31console.log('none   ->', naifVerify(none, pem));32 33// Saldırı 2: RS256 bekleyen sunucuya HS256 token, HMAC anahtarı = public key PEM'i34const h = b64({ alg: 'HS256', typ: 'JWT' });35const p = b64({ sub: '1', rol: 'admin' });36const s = crypto.createHmac('sha256', pem).update(`${h}.${p}`).digest('base64url');37console.log('HS256  ->', naifVerify(`${h}.${p}.${s}`, pem));

1$ node 02-naif.js2none   -> { sub: '1', rol: 'admin' }3HS256  -> { sub: '1', rol: 'admin' }

İlk satır none saldırısı. İkinci satır bir sonraki bölümün konusu, ama kökleri aynı: ikisinde de header.alg hangi kodun çalışacağını seçiyor.

jsonwebtoken tarafında bu konuda Aralık 2022'de çıkan 9.0.0 sürümü bir dönüm noktası. 8.5.1, none token'ını bir anahtar verildiğinde reddediyordu ama anahtar null ya da undefined geldiğinde kabul ediyordu. Kulağa uç bir durum gibi geliyor. Anahtarı bir callback'ten ya da ortam değişkeninden okuyan kodda bilinmeyen bir kid ya da unutulmuş bir .env satırı anahtarı sessizce undefined yapar. 9.0.0 ile verify, algorithms listesinde açıkça none yoksa imzasız token'ı reddediyor.

2. Algoritmayı token'dan okumak

Bu daha ince bir hata. Sunucunuz token'ları RS256 ile doğruluyor: kimlik sağlayıcı private key ile imzalıyor, siz public key ile doğruluyorsunuz. Public key adı üstünde herkese açık. Saldırgan header'ı HS256 yapar ve imzayı HMAC-SHA256 ile, anahtar olarak da sizin public key'inizin PEM metnini vererek üretir. Algoritmayı header'dan seçen doğrulayıcı elindeki tek anahtarı, yani aynı PEM metnini HMAC secret'ı olarak kullanır ve imza tutar. Yukarıdaki çıktının ikinci satırında olan buydu.

RFC 8725 bu iki saldırıyı listesinin en başına koyar ve çözümü açık yazar. Kabul edilecek algoritmaları çağıran belirler, kütüphane bunların dışında hiçbir algoritmayı kullanmaz, her anahtar tek bir algoritmaya bağlanır ve bu bağ imza kontrolü sırasında denetlenir. Aynı iki saldırı token'ını jsonwebtoken 9.0.0'a verelim.

1// 03-v9.js2const crypto = require('crypto');3const jwt = require('jsonwebtoken'); // 9.0.04const { b64 } = require('./02-naif');5 6const { publicKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });7const pem = publicKey.export({ type: 'spki', format: 'pem' });8 9const none = `${b64({ alg: 'none', typ: 'JWT' })}.${b64({ sub: '1', rol: 'admin' })}.`;10const h = b64({ alg: 'HS256', typ: 'JWT' });11const p = b64({ sub: '1', rol: 'admin' });12const hs = `${h}.${p}.${crypto.createHmac('sha256', pem).update(`${h}.${p}`).digest('base64url')}`;13 14const dene = (ad, fn) => { try { console.log(ad, '->', fn()); } catch (e) { console.log(ad, '->', e.message); } };15 16dene('none, anahtarlı         ', () => jwt.verify(none, pem));17dene('none, anahtarsız        ', () => jwt.verify(none, null));18dene('HS256, alg listesi yok  ', () => jwt.verify(hs, pem));19dene('HS256, alg: [HS256,RS256]', () => jwt.verify(hs, pem, { algorithms: ['HS256', 'RS256'] }));20dene('HS256, alg: [RS256]     ', () => jwt.verify(hs, pem, { algorithms: ['RS256'] }));

Dördüncü satır 9.0.0'ın asıl kazancı. Eskiden hem iç servislerin HMAC token'larını hem dış sağlayıcının RSA token'larını aynı middleware'den geçirmek için karışık bir liste yazan geliştirici, açığı kendi eliyle açıyordu. 9.0.0 artık anahtarın türüne bakıyor: HS ailesi için secret, RS, PS ve ES aileleri için public key istiyor. İmzalarken de 2048 bitten kısa RSA anahtarını reddediyor.

HS256 kullanıyorsanız bir ayrıntı daha var. HMAC secret'ı bir parola olamaz. Elinde tek bir geçerli token olan saldırgan, secret'ı çevrimdışı sözlük saldırısıyla deneyerek bulabilir. RFC 8725, ezberlenebilecek bir parolanın doğrudan HMAC anahtarı yapılmasını yasaklar. openssl rand -base64 32 ile üretilen 256 bitlik rastgele bir değer HS256 için yeterli.

3. kid değerine güvenmek

Birden çok anahtarınız olduğunda token'ın hangisiyle imzalandığını header'daki kid söyler. RFC 7515'e göre kid bir ipucudur ve yapısı tanımsızdır. Ne yazacağına token'ı üreten karar verir, token'ı saldırgan da üretebilir. Aşağıdaki kodda anahtarlar keys/ klasöründe dosya olarak duruyor ve doğrulayıcı kid'i dosya adı olarak kullanıyor.

1// 04-kid.js2const fs = require('fs');3const path = require('path');4const crypto = require('crypto');5const { promisify } = require('util');6const jwt = require('jsonwebtoken'); // 9.0.07const { b64 } = require('./02-naif');8const verify = promisify(jwt.verify);9 10// Yanlış: kid doğrudan dosya yoluna giriyor11function naifAnahtar(header, cb) {12  fs.readFile(path.join(__dirname, 'keys', header.kid), cb);13}14 15// Doğru: kid yalnızca bilinen bir tablodaki anahtarı seçer16const ANAHTARLAR = new Map([['2023-06', fs.readFileSync(path.join(__dirname, 'keys', '2023-06'))]]);17function guvenliAnahtar(header, cb) {18  const k = ANAHTARLAR.get(header.kid);19  if (!k) return cb(new Error(`bilinmeyen kid: ${String(header.kid).slice(0, 40)}`));20  cb(null, k);21}22 23// Saldırgan /dev/null'u gösteriyor: boş dosya, boş HMAC anahtarı24const h = b64({ alg: 'HS256', typ: 'JWT', kid: '../../../../../../../../dev/null' });25const p = b64({ sub: '1', rol: 'admin' });26const s = crypto.createHmac('sha256', Buffer.alloc(0)).update(`${h}.${p}`).digest('base64url');27const token = `${h}.${p}.${s}`;28 29(async () => {30  for (const [ad, getKey] of [['naif', naifAnahtar], ['güvenli', guvenliAnahtar]]) {31    try {32      console.log(ad.padEnd(8), '->', await verify(token, getKey, { algorithms: ['HS256'] }));33    } catch (e) {34      console.log(ad.padEnd(8), '->', e.message);35    }36  }37})();

1$ node 04-kid.js2naif     -> { sub: '1', rol: 'admin' }3güvenli  -> error in secret or public key callback: bilinmeyen kid: ../../../../../../../../dev/null

Bu sefer kütüphane jsonwebtoken 9.0.0 ve token yine geçti. İmza kontrolü doğru çalıştı, sorun ona verilen anahtarda. /dev/null boş döner, boş bir HMAC anahtarıyla imzayı da herkes üretir. Aynı hata başka kılıklarda da gelir. kid bir SQL sorgusuna girerse ' UNION SELECT 'bildigim-sir gibi bir değerle anahtarı saldırgan seçer. Header'daki jku ya da x5u alanından anahtar adresi okuyup oraya istek atan kod, saldırganın sunduğu anahtarı kabul eder ve sunucunuzu iç ağa istek atan bir araca çevirir (SSRF). RFC 8725, kid üzerinden enjeksiyonu ve jku üzerinden SSRF'i aynı başlık altında ele alır: gelen claim'lere güvenmeyin.

Çözümde kid yalnızca önceden yüklenmiş bir sözlükte arama anahtarı olur. Map ya da JWKS fark etmez. Sözlükte karşılığı yoksa token reddedilir ve başka hiçbir yola sapılmaz. JWKS adresi de token'dan değil yapılandırmadan gelir.

JWKS önbelleği ve anahtar rotasyonu

Dış bir kimlik sağlayıcı kullanıyorsanız public key'ler bir JWKS (JSON Web Key Set) adresinden gelir. Her istekte bu seti indirmek hem yavaştır hem de sizin trafiğinizi sağlayıcıya yükler. Seti süresiz önbellekte tutmak ise sağlayıcı anahtar değiştirdiği anda bütün isteklerinizi reddettirir.

jose'nin createRemoteJWKSet fonksiyonu bu dengeyi hazır kurar. 4.14.4'teki varsayılanlar kaynak kodda şöyle: set 10 dakika (cacheMaxAge) önbellekte kalır, bilinmeyen bir kid gelince set yeniden indirilir ama son indirmeden sonraki 30 saniye (cooldownDuration) içinde indirilmez, istek de 5 saniyede (timeoutDuration) zaman aşımına düşer. Bekleme süresi, rastgele kid'lerle gelen birinin sunucunuzu sağlayıcıya istek yağdıran bir araca çevirmesini engeller. Aşağıdaki çıktı, birazdan kuracağımız doğrulayıcının yeni bir anahtarla karşılaştığı anı gösteriyor. Denemede JWKS'i kimlik sağlayıcıyı taklit eden küçük bir yerel HTTP sunucusu yayımlıyor, ikinci deneme saat 31 saniye ileri alınarak yapıldı.

1$ node 06-jose.mjs2yeni kid, hemen        -> ERR_JWKS_NO_MATCHING_KEY no applicable key found in the JSON Web Key Set3yeni kid, 31 sn sonra  -> OK sub = 424JWKS isteği: 2

Rotasyonun sırası bu davranıştan çıkar. Yeni anahtarı önce JWKS'e ekleyin, imzada kullanmaya en az bir bekleme süresi sonra başlayın. Eski anahtarı, onunla imzalanmış son token'ın süresi dolana kadar sette tutun. Bir anahtar sızdıysa onu setten çıkarmak da anında etki etmez. Doğrulayıcılar önbellek süresi boyunca eski seti kullanmaya devam eder, acil bir durumda bu 10 dakikayı hesaba katın.

4. Claim'leri yarım kontrol etmek

Doğru bir imza, token'ı imzalayanın yazdıklarının değişmediğini kanıtlar. Token'ın size, şu an ve bu iş için verilip verilmediği ise ayrı sorular. Bunları claim'ler cevaplar ve kütüphaneler beklediğinizden azını kendiliğinden kontrol eder.

1// 05-claims.js2const jwt = require('jsonwebtoken'); // 9.0.03const SECRET = require('crypto').randomBytes(32);4 5const sonsuz = jwt.sign({ sub: '42' }, SECRET); // exp yok6const dene = (ad, fn) => { try { console.log(ad, '->', fn()); } catch (e) { console.log(ad, '->', e.message); } };7 8dene('exp yok, düz verify   ', () => jwt.verify(sonsuz, SECRET, { algorithms: ['HS256'] }));9dene('exp yok, maxAge: 15m  ', () => jwt.verify(sonsuz, SECRET, { algorithms: ['HS256'], maxAge: '15m',10  clockTimestamp: Math.floor(Date.now() / 1000) + 3600 })); // bir saat sonrasını taklit et11 12// Başka bir servis için basılmış token13const baska = jwt.sign({ sub: '42' }, SECRET, { audience: 'raporlama', issuer: 'https://auth.ornek.com', expiresIn: '5m' });14dene('aud kontrolsüz        ', () => jwt.verify(baska, SECRET, { algorithms: ['HS256'] }).aud);15dene('aud: odeme            ', () => jwt.verify(baska, SECRET, { algorithms: ['HS256'], audience: 'odeme' }));

1$ node 05-claims.js2exp yok, düz verify    -> { sub: '42', iat: 1687900080 }3exp yok, maxAge: 15m   -> maxAge exceeded4aud kontrolsüz         -> raporlama5aud: odeme             -> jwt audience invalid. expected: odeme

exp alanı olmayan token jsonwebtoken için süresiz geçerli. RFC 7519'da exp isteğe bağlı, kütüphane de onu ancak varsa kontrol ediyor. iss ve aud için durum daha da açık: seçeneği vermezseniz kütüphane hiç bakmıyor. aud kontrol edilmeyince raporlama servisi için üretilmiş bir token ödeme API'sinde de geçiyor. RFC 8725 buna farklı JWT türlerinin birbirine karışması der ve her tür için ayrı aud ile header'da açık bir typ önerir. Access token'lar için bu değer RFC 9068'de at+jwt olarak tanımlı.

Doğrulama başarısız olduğunda dönülecek kod 401, token geçerli ama yetki yetmiyorsa 403. Bu ayrımı HTTP durum kodlarını anlattığım yazıda da bulabilirsiniz. İstemci 401'i görünce token yenilemeyi dener, 403'te denemez, kodları karıştırmak gereksiz yenileme döngüsü üretir.

Saat kayması ve clockTolerance

Token'ı üreten sunucuyla doğrulayan sunucunun saatleri birkaç saniye farklıysa yeni üretilmiş bir token nbf yüzünden reddedilir ya da süresi dolmak üzere olan bir token bir sunucuda geçip öbüründe kalır. RFC 7519 bunun için küçük bir pay bırakmaya izin verir ve bu payın genellikle birkaç dakikayı geçmediğini söyler. İki kütüphanede de clockTolerance saniye cinsinden. Ben 30 saniyeyi yeterli bulurum. Daha büyük bir paya ihtiyaç duyuyorsanız önce sunucuların NTP ayarına bakın.

Hepsi bir arada: jose ile doğrulayıcı

1// 06-jose.mjs (doğrulayıcı kısmı)2import { createRemoteJWKSet, jwtVerify } from 'jose'; // 4.14.43 4const JWKS = createRemoteJWKSet(new URL(JWKS_URL)); // adres yapılandırmadan gelir, token'dan değil5 6async function dogrula(token) {7  const { payload } = await jwtVerify(token, JWKS, {8    algorithms: ['RS256'],              // listeyi sunucu belirler, token değil9    issuer: 'https://auth.ornek.com',10    audience: 'odeme-api',11    requiredClaims: ['exp', 'sub'],     // exp'siz token reddedilsin12    maxTokenAge: '1h',                  // iat çok eskiyse reddet13    clockTolerance: 30,                 // saniye14  });15  return payload;16}

1$ node 06-jose.mjs2geçerli                -> OK sub = 423exp yok                -> ERR_JWT_CLAIM_VALIDATION_FAILED missing required "exp" claim420 sn önce dolmuş      -> OK sub = 42590 sn önce dolmuş      -> ERR_JWT_EXPIRED "exp" claim timestamp check failed6başka aud              -> ERR_JWT_CLAIM_VALIDATION_FAILED unexpected "aud" claim value7alg none               -> ERR_JOSE_ALG_NOT_ALLOWED "alg" (Algorithm) Header Parameter not allowed

20 saniye önce dolmuş token 30 saniyelik pay sayesinde geçti, 90 saniye önce dolmuş olan geçmedi. maxTokenAge verdiğiniz anda iat de zorunlu hâle gelir. iat taşımayan bir token, aud kontrolüne sıra gelmeden missing required "iat" claim hatasıyla reddedilir. Sağlayıcınızın iat koyduğundan emin değilseniz bu seçeneği açmadan önce bakın.

5. JWT'yi oturum gibi kullanmak

Buraya kadar her şeyi doğru yaptığınızı varsayalım. Kullanıcı çıkış yaptı, şifresini değiştirdi ya da hesabı kapatıldı. Elindeki access token'ın süresinin dolmasına 50 dakika var. Ne olur? Hiçbir şey. İmzalı token kendi kanıtını taşır ve sunucu ona veritabanına bakmadan inanır. Stateless olmanın bedeli bu: iptal için bir yere bakmanız gerekir, baktığınız anda da stateless olmaktan çıkarsınız.

JWT'nin en rahat çalıştığı yer servisler arası yetkilendirme. Bir API gateway kimliği doğrular, arkadaki REST servislerine imzalı bir iddia taşır, her servis veritabanına gitmeden karar verir. Tek alan adında çalışan klasik bir web uygulamasında ise sunucu tarafı oturum ile bir httpOnly cookie, iptal sorununu baştan çözer. JWT'yi yine de kullanacaksanız işleyen düzen şöyle:

• Access token 5 ila 15 dakika yaşasın. Geri alınamayan pencere bu kadar kalır.
• Refresh token JWT olmasın. Rastgele üretilmiş, veritabanında özeti tutulan opak bir değer olsun. İptal etmek bir satırı silmek demektir.
• Her yenilemede refresh token da değişsin. Kullanılmış bir refresh token yeniden gelirse biri onu kopyalamıştır, aynı zincirden üretilmiş bütün token'ları iptal edin.
• Anında iptal şartsa jti değerleriyle bir kara liste tutun. Listedeki kayıt yalnızca token'ın exp anına kadar yaşar, Redis'te TTL ile tutmak kolaydır.

localStorage mı, httpOnly cookie mi

Token'ı tarayıcıda nerede tuttuğunuz, XSS ile CSRF arasında bir seçimdir. localStorage'daki değeri sayfada çalışan her JavaScript okur. Tek bir XSS açığı token'ın saldırganın sunucusuna gitmesine yeter ve token süresi dolana kadar başka bir makineden kullanılır. httpOnly cookie'yi JavaScript okuyamaz. Ama tarayıcı onu her istekte kendiliğinden gönderdiği için CSRF kapısı açılır.

httpOnly cookie XSS'i çözmez, yalnızca çalınan şeyin ömrünü sekmenin ömrüne indirir. Ben tarayıcı uygulamalarında access token'ı bellekte, refresh token'ı HttpOnly; Secure; SameSite=Strict; Path=/auth/refresh bir cookie'de tutmayı tercih ederim. API çağrıları Authorization başlığıyla gittiği için CSRF'e açık değildir, refresh cookie'si de yalnızca tek bir endpoint'e gider.

Sonuç

Doğrulama kodunuza bakarken her satıra tek bir soru sorun: bu satır kararı kimden alıyor? alg, kid, jku, exp'in var olup olmadığı... Bunların hepsi token'ın içinden okunabilir ve hepsi saldırganın yazabileceği alanlar. Algoritma listesi, anahtar tablosu, JWKS adresi, zorunlu claim'ler ve tolerans yapılandırmada durur, token yalnızca bunlarla karşılaştırılır. Token'dan bir değer okuyup ona göre dallanan bir satır gördüğünüzde onu hata sayın. Aksi kanıtlanana kadar da öyle kalsın.