JWT Tokenları: Nasıl Çözülür, Doğrulanır ve Yaygın Hatalardan Kaçınılır

Bir JWT, nokta ile birleştirilmiş üç base64url kodlu dizedir. Birincisi meta veri, ikincisi asıl önem taşıyan veri ve üçüncüsü ilk ikisinin değiştirilmediğini kanıtlayan imzadır. JWT hatalarının çoğu üçüncü kısmı isteğe bağlı olarak ele almaktan ya da biçimin baştan ne garanti ettiğini yanlış yorumlamaktan kaynaklanır.

Üç bölümlü yapı

Bir JWT şöyle görünür:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNzQ4NjQ4MDAwfQ.qZdfL_HxR_eRT3z3qZX7Rqv0kK7r0sQYMfRBlLcM2hI

Noktalara göre böldüğünüzde başlık, yük ve imzayı elde edersiniz. İlk iki bölümün her biri, base64url kodlu bir JSON nesnesidir —+ yerine -, / yerine _kullanan ve doldurmayı atlayan URL güvenli bir base64 varyantı. Herhangi bir tokenı JWT çözücümüze yapıştırarak üç bölümün düz JSON olarak genişletilmiş halini görebilirsiniz.

Başlık

{
  "alg": "HS256",
  "typ": "JWT"
}

İki alan. alg imzalama algoritmasını belirtir; değerler aşağıda ele alınmaktadır. typ, tokenı JWT olarak tanımlar — bazı araçlar bunu zorunlu kılar, çoğu görmezden gelir. Bazı tokenlar ayrıca doğrulayıcının bir anahtar kümesinden hangi açık anahtarı kullanacağını bilmesi için kid(anahtar kimliği) içerir.

Yük

{
  "sub": "1234567890",
  "iat": 1748648000,
  "exp": 1748651600,
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com"
}

Seçtiğiniz herhangi bir JSON nesnesi. Bu alanlara taleplerdenir. RFC 7519, anlamları sizinkiyle örtüştüğünde yeniden kullanmanız gereken yedi “kayıtlı” talep adı tanımlar.

İmza

İmza, base64url(başlık) + “.” + base64url(yük) üzerinden başlıkta belirtilen algoritma ve anahtar kullanılarak hesaplanır. İmzanın kendisi üçüncü base64url kodlu bölümdür. JWT'yi düz bir base64 zarfından ayıran şey budur.

Kayıtlı talepler

• iss (yayıncı). Tokenı kim oluşturdu. Genellikle kimlik doğrulama hizmetinizi tanımlayan bir URL. Doğrulayıcılar bunun beklenen yayıncıyla eşleştiğini kontrol etmelidir.
• sub (konu). Token kimin hakkında — genellikle kullanıcı kimliği. Yayıncı içinde benzersiz olmalıdır.
• aud (hedef kitle). Token kime yönelik — API URL'si veya hizmet adı. Beklenen hedef kitleyle eşleşmeyen bir doğrulayıcı tokenı reddetmelidir; aksi hâlde bir hizmete yönelik token başka bir hizmete karşı tekrarlanabilir.
• exp (son kullanma). Tokenın geçersiz olduğu Unix zaman damgası (1970-01-01 UTC'den bu yana saniye). Doğrulayıcılar süresi dolmuş tokenları reddetmelidir.
• nbf (önce değil). Tokenın geçersiz olduğu Unix zaman damgası. İsteğe bağlı.
• iat (oluşturulma zamanı). Tokenın ne zaman verildiğini gösteren Unix zaman damgası. Bilgilendirme amaçlı.
• jti (JWT kimliği). Tokenın kendisi için benzersiz bir kimlik; açık iptal veya tekrar saldırılarını önlemek için kullanışlıdır.

Bunların ötesinde yüke JSON serileştirilebilir herhangi bir alan ekleyebilirsiniz. Kural olarak özel taleplere gelecekteki kayıtlı adlarla çakışmayı önlemek için URL ad alanı eklenir (örn.“https://example.com/roles”).

HS256 vs RS256 vs ES256

HS256 (HMAC-SHA-256, simetrik)

İmza, paylaşılan bir gizli anahtar kullanılarak kodlanmış başlık ve yük üzerinden hesaplanan bir HMAC'tir. İmzayı doğrulayabilen herkes aynı anahtarla yeni bir imza da oluşturabilir.

Yayıncı ve doğrulayıcı aynı tarafsa (aynı hizmet, aynı gizli) HS256 kullanın. Üçüncü tarafların tokenlarınızı doğrulaması gerekiyorsa HS256 kullanmayın — imzalama gizlisini paylaşmak zorunda kalırsınız, bu da onların sizin tokenlarınız gibi görünen tokenlar oluşturabilmesi anlamına gelir.

RS256 (RSA-SHA-256, asimetrik)

İmza, yayıncının özel anahtarını kullanan bir RSA imzasıdır. Doğrulayıcılar, genellikle bir JWKS uç noktasında yayımlanan yayıncının açık anahtarını kullanarak imzayı kontrol eder. Doğrulayıcılar token oluşturamaz.

Bu, birleşik kimlik için varsayılandır: OpenID Connect, Auth0, Cognito, her “X ile giriş” akışı. Yayıncı özel anahtarı saklar; diğer herkes açık anahtara güvenir.

ES256 (P-256 üzerinde ECDSA, asimetrik)

RS256 ile aynı güvenlik modeli ancak eliptik eğri imzalarıyla. Avantajları: ~10 kat daha küçük imza boyutu (64 bayt vs 256), daha hızlı doğrulama ve bit başına daha güçlü güvenlik. Dezavantajı: ECDSA uygulamalarının yanlış gitmesi RSA'dan daha kolaydır ve tarihsel olarak kritik hatalar üretmiştir (PlayStation 3'teki “k yeniden kullanımı” felaketi, Java CVE-2022-21449 “psişik imzalar” hatası).

ES256'yı denetlenmiş bir kütüphaneyle kullanın (Node'un yerleşik crypto modülü, Go'nun crypto/ecdsa, Rust'ın ring, Python'ın cryptography paketi). Kendi ECDSA'nızı hiçbir zaman yazmayın.

EdDSA (Ed25519)

ES256'dan daha yeni, yanlış kullanımı daha zor, asimetrik seçeneklerin en hızlısı. RFC 8037'de JWT algoritması olarak listelenir ancak evrensel olarak desteklenmez — benimsemeden önce yığınınızı kontrol edin.

alg: none saldırısı

JWT şartnamesi “imzasız” anlamına gelen özel bir algoritma değeri tanımlar: none. alg: none içeren bir tokenın boş bir imza bölümü vardır — noktalar hâlâ oradadır ancak üçüncü kısım boş dizedir.

2015 yılında araştırmacılar, birçok JWT kütüphanesinin başlıktakialg alanını doğrulama talimatı olarak dikkate aldığını gösterdi. Bir saldırgan meşru bir HS256 tokenı alıp başlığı alg: noneolarak değiştirebilir, imzayı düşürebilir; kütüphane değiştirilmiş tokenı, “algoritmaya göre imza gerekmiyor” gerekçesiyle geçerli olarak kabul ederdi.

Hafifletme yöntemi, doğrulamayı tokenın iddia ettiği algoritmaya değil beklenen algoritmaya karşı yapmaktır:

// YANLIŞ — başlığa güvenir
jwt.verify(token, key);

// DOĞRU — algoritmayı sabitler
jwt.verify(token, key, { algorithms: ["RS256"] });

Modern kütüphaneler none'ı varsayılan olarak reddeder ya da açık bir onay gerektirir. RFC 8725 (JWT En İyi Güncel Uygulamalar), algoritma sabitleme kalıbını zorunlu kılar. Bunu takip etmeyen doğrulama kodlarını denetleyin.

Diğer yaygın hatalar

kid başlığını doğrulama olmadan güvenmek

kid başlığı, doğrulayıcıya bir anahtar kümesinden hangi anahtarı kullanacağını söyler. kid'i körce dosya yolu veya veritabanı anahtarı olarak kullanırsanız saldırgan kötü amaçlı bir değer (../../etc/passwd veya SQL enjeksiyonu) sağlayabilir. kid'i her zaman bilinen bir kümeye opak bir arama anahtarı olarak, yol ya da sorgu olarak değil, ele alın.

Algoritma karışıklığı (RS256 → HS256)

Bazı kütüphaneler RS256 doğrulaması için açık anahtarı kabul eder ancak aynı zamanda HS256 için HMAC gizlisi olarak da kabul eder. Saldırgan başlığı RS256'dan HS256'ya değiştirip tokenı, HMAC gizlisi olarak (herkese açık) RSA açık anahtarıyla imzalayabilir; kütüphane doğrular. Algoritmayı sabitleyin.

İptal mekanizması olmayan uzun ömürlü erişim tokenları

JWT'ler durumsuz olup doğrulayıcı her istek için yayıncıyla iletişim kurmaz. Tüm performans kazanımı budur ve tüm iptal sorunu da. Sunucu taraflı bir ret listesi tutmadan exptarihinden önce sızan bir tokenı geçersiz kılamazsınız; bu durumsuzluğu ortadan kaldırır.

Standart kalıp: kısa ömürlü erişim tokenı (5-60 dakika) artı sunucu tarafında saklanan uzun ömürlü yenileme tokenı (günler ila haftalar). Kullanıcı çıkış yaptığında, bir cihaz kayboldu olarak bildirildiğinde veya yönetici yeniden kimlik doğrulamayı zorladığında yenileme tokenını iptal edin. Erişim tokenı kısa süre içinde kendi kendine sona erer.

Yüke gizli bilgi koymak

Yük base64url kodludur, şifreli değil. Tokenı elinde bulunduran herkes her talebi okuyabilir. Parola, API anahtarı, sıkı düzenlemeye tabi kişisel veri veya sunucu günlüğüne yazmak istemeyeceğiniz başka hiçbir şeyi koymayın. Gizlilik gerekiyorsa JWE kullanın.

Hedef kitle ve yayıncı doğrulamasını atlamak

İmzayı kontrol eden ancak aud ve isstaleplerini doğrulamayan bir doğrulayıcı, başka bir hizmet için oluşturulan tokenları kabul eder. Birleşik bir ortamda bu kritik bir hatadır. RFC 8725, ikisinin de beklenen değerlere karşı doğrulanması gerektiğini belirtir.

JWT'leri localStorage'da saklamak

localStorage, kökünüzdeki herhangi bir JavaScript tarafından okunabilir; bu da her XSS'in tam bir token çalınmasına dönüşeceği anlamına gelir. Tarayıcıda saklanan tokenlar için üstüne bir CSRF stratejisi eklenmiş HTTP-only güvenli çerezleri tercih edin. localStorage kullanmanız gerekiyorsa XSS savunmalarınız kusursuz olmalıdır.

JWT yanlış araç olduğunda

JWT belirli bir sorunu çözer: doğrulayıcının yayıncıyla iletişim kurmadan bir talebe güvenmesi gerekir. Bu sorun birleşik kimlik ve mikro hizmetlerde gerçekten vardır. Genellikle istemcinin ve sunucunun aynı ekip tarafından işletildiği birinci taraf bir web uygulamasında yoktur.

Bu durumda HTTP-only güvenli çerezle sunucu taraflı düzenli bir oturum daha basittir:

• Anında iptal edilebilir. Oturum satırını silin, kullanıcı çıkış yapmış olsun.
• Ağ üzerinde daha küçük. Oturum kimliği 30 baytlık bir çerezdir; JWT 500-2.000 bayt olabilir.
• Daha basit güvenlik modeli. Algoritma karışıklığı hatası yok, alg: none yok, yük gizliliği karışıklığı yok.
• İnsanların iddia ettiğinden daha ölçeklenebilir. İstek başına Redis veya veritabanı araması en fazla bir milisaniye ekler. JWT'nin performans argümanı ölçüldüğünde çoğunlukla erir.

JWT, kullanıcı kimliğine merkezi bir oturum deposuyla konuşmadan güvenmesi gereken birden fazla hizmetiniz olduğunda ya da üçüncü taraflara token verdiğinizde karmaşıklığına değer — ki bu tam olarak OAuth 2.0 / OpenID Connect akışında JWT'lerin oynadığı roldür; yetkilendirme sunucusu, kaynak sunucusunun çevrimdışı olarak doğrulayabileceği imzalı bir erişim veya kimlik tokenını istemciye teslim eder. Kendi arka ucuyla konuşan tek bir uygulama için çerez sıkıcı ama doğru yanıttır.

Güvenli bir doğrulama şablonu

// Node.js, jsonwebtoken kütüphanesi
import jwt from "jsonwebtoken";

function verifyToken(token: string): Payload {
  return jwt.verify(token, publicKey, {
    algorithms: ["RS256"],          // algoritmayı sabitle
    issuer: "https://auth.example.com",   // yayıncıyı sabitle
    audience: "https://api.example.com",  // hedef kitleyi sabitle
    clockTolerance: 5,              // saat kayması için küçük pay
  }) as Payload;
}

Beş satır seçenek, dördü doğrudan yukarıdaki saldırıları hafifletir. 2026'da tüm JWT kütüphanelerinin varsayılanları 2015'tekinden daha güvenlidir; ancak sessiz kimlik doğrulama atlaması söz konusu olduğunda açık yine de örtük olandan iyidir.

Dürüst çıkarım

Bir JWT'yi çözmek önemsizdir — base64url, böl, JSON ayrıştır. Tarayıcı içi çözücümüz tokenı hiçbir yere göndermeden bunu yapar; bu önemlidir çünkü tokenlar çoğunlukla üçüncü taraf bir siteye yapıştırmak istemeyeceğiniz tanımlayıcı talepler içerir.

Algoritmayı sabitlediğiniz, iss, aud veexp'ı doğruladığınız ve başlığın nasıl doğrulayacağınızı söylemesine asla güvenmediğiniz sürece JWT doğrulamak da basittir. Yayıncı ve doğrulayıcı aynı tarafsa HS256, aksi durumda denetlenmiş bir kütüphaneyle RS256 veya ES256 seçin. Ve JWT'ye başvurmadan önce sıkıcı bir oturum çerezinin işi görmeyeceğini kontrol edin.