JWT (JSON Web Token) Mimarisi, İmzalar ve Güvenlik Rehberi

1. RFC 7519 JSON Web Token Anatomisi

JSON Web Token (JWT); iki taraf arasında güvenli şekilde JSON nesnesi biçiminde bilgi aktarımı sağlayan kompakt, URL-güvenli bir standarttır (RFC 7519). Bir JWT noktalarla (.) ayrılmış üç temel bileşenden meydana gelir:

Header (Başlık), Payload (Gövde) ve Signature (İmza). İlk iki bileşen yalnızca Base64URL ile kodlanmıştır; yani herhangi bir şifreleme içermez ve herkes tarafından okunabilir. Güvenliği sağlayan tek unsur ise üçüncü parça olan kriptografik imzadır.

// 1. Header (Kullanılan algoritma ve token türü)
{
  "alg": "HS256",
  "typ": "JWT"
}

// 2. Payload (Kullanıcı kimliği ve standart claim'ler)
{
  "sub": "usr_94819284",
  "name": "Mustafa Yılmaz",
  "role": "admin",
  "iat": 1730000000,
  "exp": 1730003600
}

// 3. Signature (Başlık ve gövdenin gizli anahtarla imzalanmış hali)
// HMACSHA256(base64Url(header) + "." + base64Url(payload), secretKey)

2. HMAC Simetrik vs RSA/ECDSA Asimetrik İmzalar

JWT imzalama protokollerinde iki temel kriptografik yaklaşım kullanılır:

Simetrik algoritmalar (HS256, HS384, HS512), token'ı üretirken ve doğrularken aynı gizli anahtarı (shared secret) kullanır. Bu yöntem tek bir monolitik backend sisteminde hızlıdır ancak anahtarın mikroservisler arasında dağıtılması güvenlik riski yaratır.

Asimetrik algoritmalar (RS256, ES256) ise bir açık (public) ve bir özel (private) anahtar çiftinden yararlanır. Kimlik doğrulama sunucusu (Auth Server) token'ı özel anahtarla imzalar; API ağ geçitleri veya istemciler ise token'ı sadece açık anahtarla güvenle doğrular.

3. Kritik Güvenlik Açıkları ve Korunma Yolları

JWT entegrasyonlarında sıkça yapılan ve sistemlerin ele geçirilmesine yol açan güvenlik hataları şunlardır:

1. 'alg: none' Zafiyeti: Eski veya hatalı yapılandırılmış kütüphaneler, header'da 'alg': 'none' gönderildiğinde imza doğrulamasını devre dışı bırakır. Bu durum saldırganın herhangi bir parola bilmeden admin rolü almasına izin verir. Çözüm: Backend doğrulamalarında algoritma listesi kesin olarak sınırlandırılmalıdır (whitelisting).

2. Zayıf Parola ile HS256 İmzası: Kısa ve tahmin edilebilir parolalar (örneğin 'secret123') hashcat gibi araçlarla saniyede milyarlarca kombinasyon denenerek dakikalar içinde kırılabilir. En az 256-bit entropiye sahip kriptografik rastgele dizeler kullanılmalıdır.

4. Web Crypto API ile Tarayıcı İçi Güvenli Doğrulama

Yazılım Motoru JWT Debugger, girdiğiniz token'ı sunucuya iletmeden doğrudan W3C standartlarındaki Web Crypto API (SubtleCrypto) arayüzünü kullanarak tarayıcınızın belleğinde ayrıştırır ve imzasını doğrular:

async function verifyJwtHs256(token, secret) {
  const [headerB64, payloadB64, signatureB64] = token.split('.');
  const dataToVerify = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
  
  // 1. Gizli anahtarı CryptoKey formatına dönüştür
  const key = await window.crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['verify']
  );
  
  // 2. Base64Url imza baytlarını çöz
  const rawSignature = Uint8Array.from(atob(signatureB64.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0));
  
  // 3. İmzayı güvenle doğrula
  const isValid = await window.crypto.subtle.verify(
    'HMAC',
    key,
    rawSignature,
    dataToVerify
  );
  
  return isValid;
}

5. Token Saklama Güvenliği: HttpOnly Cookie vs LocalStorage

Tarayıcıda JWT saklarken en yaygın hata token'ı LocalStorage içine yazmaktır. LocalStorage içindeki tüm verilere sayfadaki herhangi bir JavaScript kodu erişebilir; bu da sitenizde oluşabilecek tek bir XSS (Cross-Site Scripting) açığında oturumunuzun tamamen çalınması anlamına gelir.

En güvenli mimari; JWT token'ının backend tarafından HttpOnly, Secure ve SameSite=Strict bayraklarıyla işaretlenmiş bir çerez (cookie) içinde saklanmasıdır. Bu sayede tarayıcıdaki hiçbir zararlı script token verisine doğrudan ulaşamaz.