JWT Aracı (Çöz / Doğrula / İmzala)

JSON Web Token’lar modern web’in fiilî kimlik doğrulama temel taşı; ama bunları her gün kullanan şaşırtıcı sayıda geliştirici, ‘auth uç noktasından dize geri alıyorum ve sonraki isteklerin Authorization başlığına koyuyorum’un ötesinde yapıyı tam anlamış değil. Token’ın kendisi noktalarla ayrılmış üç Base64URL kodlu segment — imzalama algoritmasını ve anahtar tanımlayıcısını açıklayan başlık, kullanıcı veya oturum hakkındaki iddiaları içeren yük ve token’ın imzalama anahtarının sahibi tarafından düzenlendiğini kanıtlayan imza. Formatın hem dehası hem laneti, ilk iki parçanın Base64URL’i çözebilen herkes tarafından önemsiz biçimde okunabilir olması; güvenlik tamamen imzaya bağlı, içeriğin gizli olmasına değil.

Bir JWT’yi içeriğini incelemek için çözmek, çoğu geliştiricinin tanımadığı bir token verildiğinde yapmak istediği ilk şey ve çözmenin doğrulamayla aynı şey olmadığını hatırladığın sürece tamamen güvenli bir operasyon. Buradaki araç başlığı ve yükü net biçimlendirmeyle çözüyor, standart iddiaları (iss, sub, aud, exp, nbf, iat, jti) uygun tip ipuçlarıyla görüntülüyor ve zamana duyarlı iddialar için ‘şu kadar süre sonra sona eriyor’ geri sayımı gösteriyor; böylece bir token’ın duvar saatine göre hâlâ geçerli olup olmadığını anında görebiliyorsun. Özel iddialar etiketli JSON olarak görünüyor; bu da uygulamaya özgü veriyi belirlemeyi kolaylaştırıyor.

İmza doğrulaması güvenliğin gerçekten yaşadığı yer ve aracın sıkı mod doğrulayıcısı, çoğu açık JWT kütüphanesinin yıllar içinde ince algoritma ile ilgili hatalar üzerinden kimlik doğrulama atlatmalarının kaynağı olduğu için var. ‘alg=none’ atlatması — bir token’ın algoritma yok dediği ve naif doğrulayıcıların geçerli kabul ettiği — bilmesi gereken şirketlerde yüksek profilli ihlallerden sorumlu oldu. Buradaki sıkı mod alg=none’u koşulsuz reddediyor, doğrulamadan önce kabul edilebilir algoritmaların izin listesini gerektiriyor ve anahtar/algoritma karmaşasını önlüyor (HS256 için HMAC sırrı olarak RSA açık anahtarı kullanmak, sıkı modun engellediği klasik bir istismar deseni).

Desteklenen algoritmalar gerçek dünya JWT yelpazesinin tamamını kapsıyor. HS256/HS384/HS512 (SHA-2 ile HMAC) simetrik — her iki tarafta aynı sır — ve tüketicinin paylaşılan sırrı tuttuğu makineden makineye API’larda yoğun kullanılıyor. RS256/RS384/RS512 (PKCS1.5 ile RSA) ve PS256/PS384/PS512 (RSA-PSS) asimetrik — doğrulama için açık anahtar, imzalama için özel anahtar — ve tüketicilerin token sahteciliği yapamaması gereken OIDC ve federasyon senaryolarında yoğun kullanılıyor. ES256/ES384/ES512 (ECDSA) modern asimetrik seçenek; RSA’dan daha küçük imzalar ve daha hızlı doğrulama. Doğru algoritma tehdit modeline ve düzenleyici ile tüketici arasındaki güven ilişkisine bağlı.

JWKS desteği herhangi bir üretim JWT doğrulaması için önemli; çünkü pratikte rotasyonel anahtar sistemlerinin nasıl çalıştığı bu. Bir JWKS uç noktası düzenleyicinin mevcut açık anahtarlarını JSON belge olarak ifşa ediyor; tüketiciler onu çekiyor, token başlığındaki kid (anahtar kimliği) ile eşleşen anahtarı buluyor ve o belirli anahtara karşı doğruluyor. Buradaki araç bir URL’den JWKS çekebiliyor veya yapıştırılmış JWKS belgesi kabul edebiliyor, kid’e göre doğru anahtarı otomatik seçiyor ve hangi anahtarın kullanıldığını gösteriyor. Auth0, Okta, Google Identity Platform, AWS Cognito ve diğer çoğu kimlik sağlayıcı JWKS uç noktaları açıyor; bunları düzgün desteklemek, oyuncak örneklerde çalışan bir araçla gerçek auth akışlarını hâlleten bir araç arasındaki farkı belirliyor.

Token üretimi, çözme ve doğrulamadan daha az dikkat çeken ama test için çok önemli olan JWT işinin yarısı. Belirli iddia değerleri, son kullanma süreleri ve imzalarla yeniden üretilebilir test fikstürleri kurmak, entegrasyon testlerini güvenilir kılan şey. Buradaki imzalama yolu sırrı veya özel anahtarı kabul ediyor, token’ı seçilen algoritmayla imzalıyor ve aynı girdilere göre gerçek düzenleyicinin üreteceği token’la byte‑bayt aynı bir token üretiyor. Kimlik doğrulama korumalı uç noktalara karşı test yazan geliştiriciler için bu auth kontrolünü tamamen sahte yapmaktan çok daha iyi — testler üretimde çalışan aynı doğrulama kodunu çalıştırıyor.

exp iddiası pratikte JWT ile ilgili hataların tek başına en yaygın kaynağı. exp saniye cinsinden bir Unix zaman damgası (milisaniye değil; bu da JavaScript’in yerel zaman formatı ve 1000 ile çarpma hatalarının yaygın bir kaynağı) ve doğrulayıcının exp’si geçmiş token’ları reddetmesi gerekiyor. İnce sorunlar düzenleyici ile tüketici arasındaki saat sapmasından, son kullanma tarihinin tanınmasını geciktiren önbelleklemeden ve exp’yi varsayılan olarak zorlamayan kütüphanelerden geliyor. Buradaki sıkı mod doğrulayıcısı yapılandırılabilir saat sapma toleransıyla exp, nbf (not before) ve iat (issued at) kontrolü yapıyor; bu da çoğu zamanlama ile ilgili sorunu kaynağında yakalıyor.

Yaygın tuzaklar arasında token’ları imza yerine şifreleme olarak ele almak (herkes JWT okuyabilir, imza yalnızca özgünlüğü kanıtlıyor), token’ları XSS saldırılarının okuyabildiği localStorage’da saklamak (tarayıcı tokenları için daha iyi desen httpOnly çerezler), iddialara hassas veri gömmek (kişisel veri, dahili kullanıcı tanımlayıcıları, token sahibine görünmemesi gereken her şey) ve zayıf paylaşılan sırla HS256 kullanmak (bu da saldırgana tek bir token verildiğinde sırrı kaba kuvvetle çözmesine olanak veriyor) bulunuyor. Buradaki araç bu kalıpları doğrudan zorlamıyor; ama etrafındaki belgeleme sorunları geliştirme sırasında görünür kılıyor; bu da onları ele almanın doğru zamanı.

Türkiye’de JWT ile çalışan geliştiriciler için özel bir not. Hem yerli kimlik servisleri (e‑Devlet entegrasyonları için OAuth/OIDC) hem de uluslararası sağlayıcılar (Auth0, Okta, AWS Cognito) Türk şirketlerinde yaygın. Yerel ödeme entegrasyonları (Iyzico, PayTR), KEP servisleri ve banka API’ları zaman zaman kendi JWT varyantlarını kullanıyor; bunların doğrulanması için sağlayıcının dokümantasyonunda belirtilen tam algoritmayı ve anahtar formatını kullanmak gerekli. Sıkı modun ‘izin verilen algoritmalar listesi’ özelliği bu durumlarda özellikle değerli; üretimdeki gerçek davranışı yerelde tam olarak yeniden üretmek isteyen ekipler için bir test güvencesi.

Gizlilik ve operasyonel notlar. Token içerikleri WebCrypto kullanılarak tamamen tarayıcıda işleniyor; kullanıcının token, sır veya anahtarlarının sunucu tarafında işlenmesi yok. JWKS çekme işlemleri tarayıcıdan doğrudan JWKS URL’ine gidiyor; bu sitenin sunucuları üzerinden proxy yok. Üretim token’larıyla (genelde gerçek kullanıcı verisi içeren) çalışan geliştiriciler için bu önemli; çünkü hassas materyali üçüncü taraf bir araca yüklemek, bir hata ayıklayıcıya sahip olmanın amacını boşa çıkarıyor; tarayıcı tarafı modeli aracın yeni ifşa yolları yaratmadan üretim hata ayıklamasında kullanılabileceği anlamına geliyor.

Operasyonel olarak araç çözücü, doğrulayıcı ve imzalayıcıyı birleştiren tek çalışma alanı. Çözmek ve incelemek için token yapıştır, doğrulamak için anahtar yapıştır veya JWKS çek, sıkı modu ve izin verilen algoritmaları yapılandır, net geçer/kalır göstergeleriyle doğrulama durumunu gör. İmzalamak için başlığı ve yükü yapılandır, algoritma seç, uygun anahtarı sağla, imzalı token’ı al. Aynı oturumda birden fazla token geçebiliyor — tek seferlik bir vakanın ötesinde, ilgili token serisinde bir kimlik doğrulama hatasını kovalarken işe yarıyor. Arayüz tepkili, operasyonlar hızlı ve açıkça gönderdiklerin (JWKS URL çekme gibi) dışında hiçbir şey tarayıcıdan ayrılmıyor.

OAuth 2.0 ve OIDC entegrasyonları bu aracın pratikte en yoğun kullanıldığı yer. Tipik bir OIDC akışı yetkilendirme kodu, token değişimi ve entegrasyon sırasında doğru iddiaların mevcut olduğunu, doğru hedef kitlenin ayarlandığını ve imzanın düzenleyicinin yayımlanmış JWKS’sine karşı doğrulandığını teyit etmek için incelenmesi gereken bir dizi erişim ve kimlik tokenı içeriyor. Araç olmadan bu hata ayıklama bir yığın curl komutu, JSON biçimlendirici ve ayrı bir imza doğrulayıcı ile yapılıyor — yavaş, hata yatkın ve entegrasyon teslim tarihi baskısı altında sinir bozucu. Bu araçla aynı iş akışı yapıştır‑çöz‑doğrula’ya iniyor; bu da OIDC entegrasyon hata ayıklama oturumunun saatler yerine dakikalar sürmesi anlamına geliyor.

Refresh token yönetimi JWT işine bitişik ve sıkça karıştırılan ilgili bir kavram. Refresh tokenları tipik olarak JWT yerine opak dizeler — auth sunucusu bunları kendinden bağımsız kimlik bilgileri yerine oturum işaretçileri olarak ele alıyor — ama aynı auth akışı her ikisini de üretiyor ve geliştiriciler ara sıra refresh tokenı JWT olmasını bekleyerek çözmeye çalışıyor; çözme başarısız olduğunda kafaları karışıyor. Buradaki araç bir token’ın geçerli JWT yapısı olmadığını yanıltıcı çıktı üretmek yerine açıkça belirtiyor; bu da bu karışıklık kategorisini doğru anda yakalıyor.

Standart iddia anlamları kısa bir notu hak ediyor; çünkü standart iddiaların yanlış kullanımı tekrar eden ince hata kaynağı. iss düzenleyici URL’si ve yalnızca mevcut olmasından öte beklenen bir değere karşı kontrol edilmesi gereken bir alan. aud hedeflenen kitle ve token’lar imza geçerli olsa bile yanlış servise kendilerini reddetmeli. sub konu (tipik olarak kullanıcı tanımlayıcı) ve uygulama mantığı için birincil kullanıcı kimliği olmalı. exp/nbf/iat üçlüsü token ömrünü yönetiyor. jti token kimliği ve ara sıra iptal listeleri için kullanılıyor. Bunları belirli doğrulama beklentileriyle anlamlı alanlar yerine ‘sadece iddia’ olarak ele almak, bir servisten gelen token’ın başka bir servis tarafından kabul edildiği kimlik doğrulama atlatmalarının kaynağı.