JWT Çözücü rehberi

Bir JWT nasıl kurulur

Bir JSON Web Token (RFC 7519), kullanıcı kimliği ve son kullanma zamanı gibi talepleri sistemler arasında taşımanın kompakt bir yoludur. Noktalarla ayrılmış üç bölümden oluşur: imzalama algoritmasını adlandıran bir başlık, talepleri taşıyan bir yük ve ilk iki bölümün üzerine hesaplanan bir imza. Bölümlerin her biri base64url ile kodlanır. Ortaya çıkan dize bir HTTP başlığına, bir çereze ya da bir sorgu parametresine sığacak kadar kısadır; API'lerde ve oturum açma sistemlerinde bu kadar yaygın olmasının nedeni de budur.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9      header:    {"alg":"HS256","typ":"JWT"}
.eyJzdWIiOiIxMjMiLCJleHAiOjE3NTc5MDAwMDB9  payload:   {"sub":"123","exp":1757900000}
.3q2-7wrBx...                            signature: HMAC-SHA256 over header.payload

Başlığı ve yükü herkes çözebilir; base64url bir kodlamadır, şifreleme değildir. Token'ı güvenilir kılan şey imzadır: yalnızca doğru anahtara sahip bir taraf onu üretebilir ve başlıkta ya da yükte yapılan en küçük değişiklik imzayı bozar. Şifrelenmiş token'lar da vardır (JWE), ancak API'lerde ve oturum açma sistemlerinde dolaşan token'ların büyük çoğunluğu yalnızca imzalıdır. Bu yüzden bir token'ın içindeki hiçbir alanı gizli kabul etmeyin; token'ı ele geçiren herkes onu tam olarak bu sayfanın okuduğu gibi okur.

JWT Çözücü nasıl kullanılır

1. JWT Çözücü aracını açın ve bir token yapıştırın. Token siz yazarken tarayıcınızda çözülür.
2. Başlığı ve yükü biçimlendirilmiş JSON olarak okuyun; altındaki algoritma, son kullanma ve talep notlarını da gözden geçirin.
3. İmzayı doğrulamak için HMAC gizli anahtarını girin (anahtar bu biçimde saklanıyorsa base64url kutusunu işaretleyin) ya da PEM veya JWK biçiminde bir açık anahtar yapıştırın.
4. İmzayı doğrula düğmesine basın ve sonucu okuyun.

Kayıtlı talepler

{
  "iss": "https://auth.example.com",
  "sub": "user-8812",
  "aud": "https://api.example.com",
  "iat": 1789462800,
  "exp": 1789463700,
  "scope": "orders:read"
}

Zaman talepleri milisaniye değil, saniye cinsinden Unix zaman damgalarıdır. Çözücü bunları cihazınızın saatini kullanarak “3 saat önce süresi doldu” ya da “14 dakika daha geçerli” gibi okunabilir sürelere çevirir. Cihazın saati yanlışsa bu süreler de yanlış olur. Yeni verilmiş bir token'ın beklenmedik biçimde süresi dolmuş görünmesinin en yaygın iki nedeni budur: kayan bir cihaz saati ya da milisaniye cinsinden yazılmış bir exp değeri. Tabloda yer almayan scope, role ya da email gibi alanlar özel taleplerdir; anlamlarını standart değil, token'ı veren sistem belirler.

Çözücünün uyardığı durumlar

İmzaları doğrulamak

HMAC algoritmalarında aynı gizli anahtar hem imzalar hem doğrular; dolayısıyla doğrulayabilen herkes token da üretebilir. Asimetrik algoritmalar bu ikisini birbirinden ayırır: ihraççı özel anahtarı kendinde tutar ve açık anahtarı çoğu zaman bir JWKS belgesi olarak yayımlar, böylece herhangi bir servis token üretme yetkisi olmadan doğrulama yapabilir. Token'ları birçok servisin tükettiği sistemlerde asimetrik anahtarlar daha güvenli tasarımdır. Anahtar değişimini de kolaylaştırırlar, çünkü korunması gereken tek şey ihraççıdaki özel anahtardır.

Doğrulama, tarayıcının WebCrypto gerçekleştirimini kullanır. Başarılı bir doğrulama yalnızca token'ın eşleşen anahtarla imzalandığını kanıtlar; iss ve aud değerlerini ya da token'ın iptal edilip edilmediğini kontrol etmez, bunlar alıcı sunucunun işi olmayı sürdürür. Bu yüzden olumlu bir doğrulama sonucu tek başına “bu token benim API'm için geçerli” anlamına gelmez. Araç ayrıca bir JWKS adresini getirmez ve başlıktaki kid değerini sizin için çözümlemez; eşleşen anahtarı kendiniz yapıştırırsınız.

Yaygın JWT hataları

• Algoritmayı token'ın kendisinden kabul etmek. Beklenen algoritmaları sunucuda yapılandırın; seçimi asla alg başlığına bırakmayın, none ve anahtar karıştırma saldırıları tam olarak böyle çalışır.
• Zayıf HMAC gizli anahtarları. Kısa ya da tahmin edilebilir anahtarlar tek bir token'dan yola çıkılarak çevrimdışı kaba kuvvetle kırılabilir. En az hash çıktısı kadar rastgele bayt kullanın, örneğin HS256 için 32 bayt.
• Son kullanma tarihinin olmaması ya da çok uzun ömürler. Token'lar kolayca iptal edilemez; bu yüzden erişim token'larını kısa ömürlü tutun ve uzun oturumlar için yenileme token'ları kullanın.
• Yükte hassas veri taşımak. Yükteki her şey, token'ı elinde tutan herkes tarafından okunabilir; buna tarayıcı eklentileri, ara vekiller ve günlük kayıtları da dahildir.
• aud değerini kontrol etmemek. Bir servis için verilmiş bir token, yalnızca aynı ihraççıya güveniyor diye başka bir servis tarafından kabul edilmemelidir.
• Token'ları betiklerin okuyabileceği yerlerde saklamak. localStorage içindeki token'lar her XSS açığına açıktır; tarayıcı oturumlarında HttpOnly çerezler bunu önler.

CSP rehberi, tarayıcıda saklanan token'ları koruyan betik enjeksiyonu sınırlamasını ayrıntılı olarak ele alır. Token'ların içindeki JSON'u daha yakından incelemek için JSON Araçları çözülmüş yükleri okunaklı biçimde yazdırabilir. Her iki araç da girdiyi yalnızca tarayıcınızda işler, dolayısıyla üzerinde çalıştığınız token sayfadan hiç çıkmaz. Bir token'ın gizli anahtarını ya da açık anahtarını üretmeniz gerekiyorsa, rastgele baytları platformunuzun güvenli üreticisinden alın ve sonucu bir sır yöneticisinde saklayın.

SSS

Kaynaklar

• RFC 7519: JSON Web Token (JWT)
• RFC 7515: JSON Web Signature (JWS)
• RFC 7518: JSON Web Algorithms (JWA)
• RFC 8725: JSON Web Token için en iyi güncel uygulamalar
• RFC 7517: JSON Web Key (JWK)