JWT nedir?

JWT (JSON Web Token), bir tarafın kullanıcı veya işlem hakkında JSON claim bilgilerini taşıyan bir token biçimidir. İmza/MAC korumalı JWS veya şifreli JWE biçimleri vardır; burada yaygın imzalı erişim token’ı anlatılır. En yaygın kullanımında sunucu, başarılı girişten sonra JWT üretir; istemci bunu sonraki isteklerde gönderir; sunucu da imzayı ve geçerlilik koşullarını kontrol ederek isteğe izin verir. JWT çoğu kullanımda şifreli değildir: token’ı ele geçiren biri içindeki payload alanlarını okuyabilir, ancak imzalı alanları anahtar olmadan güvenilir biçimde değiştiremez.

JWT nasıl çalışır?​

Yaygın compact JWS biçimindeki imzalı JWT üç parçadan oluşur ve noktalarla ayrılır:

header.payload.signature

Header genellikle kullanılacak imza algoritmasını belirtir. Payload, kullanıcı kimliği ve süre gibi claim alanlarını taşır; role gibi uygulamaya özgü claim’ler ayrıca tanımlanabilir. Her JWT’nin aynı alanları taşıması standart zorunluluk değildir. Signature ise header ve payload’ın belirli bir anahtarla imzalanmış hâlidir. İlk iki bölüm Base64URL kodlamasıyla taşındığından bunları decode etmek şifre çözmek anlamına gelmez.

Örneğin bir kullanıcı giriş yaptığında sunucu, payload içinde sub=user-42 ve role=editor gibi bilgiler bulunan bir token verebilir. İstemci bunu korumalı bir API isteğinde gönderir:

Authorization: Bearer <token>

API sunucusu token’ı aldığında imzayı doğrular; ayrıca süresinin geçip geçmediğine, beklenen issuer, subject ve hedef hizmet sözleşmesine uyup uymadığına bakar. Bu, her kullanımda gerçek kişinin yeniden giriş yaptığı anlamına gelmez. Kontroller başarılıysa isteği işler. Yalnızca payload içindeki role değerini okumak yetkilendirme için yeterli değildir; imza doğrulanmadan bu değer güvenilir kabul edilemez.

JWT ile oturum akışını kurarken izlenecek yol​

1. Giriş bilgilerini doğrulayan sunucuda, kullanıcı kimliği ve gerekli sınırlı claim’leri içeren kısa ömürlü bir access token üretin. Parola, API anahtarı veya kişisel veri gibi gizli bilgileri payload’a koymayın.
2. Token’ı yalnızca TLS üzerinden istemciye iletin. Tarayıcı tabanlı uygulamalarda saklama yöntemini, XSS ve CSRF risklerini dikkate alarak seçin; hassas oturumlarda HttpOnly ve uygun SameSite özelliklerine sahip güvenli çerez yaklaşımı değerlendirilebilir.
3. Her korumalı istekte imzayı, beklenen algoritmayı, exp süresini ve uygulamanızın ihtiyaç duyduğu iss ile aud değerlerini doğrulayın. Sadece token’ın biçiminin doğru olması kabul için yeterli değildir.
4. Access token süresi dolduğunda, ayrı bir yenileme akışı kullanın veya kullanıcıdan yeniden giriş isteyin. Yenileme token’larını access token’dan daha sıkı koruyun ve iptal edilebilir bir kayıtla ilişkilendirin.
5. İmza doğrulaması başarısızsa, token süresi geçmişse veya claim kontrolleri uyuşmuyorsa isteği reddedin. Uygulama günlüklerine token’ın tamamını yazmayın; yalnızca olayın türü, kullanıcı bağlamı ve istek kimliği gibi sınırlı teşhis bilgilerini kaydedin.

Başarılı doğrulama, token’ın değiştirilmediğini ve beklenen anahtarla imzalandığını gösterir; tek başına kullanıcının hâlâ aktif olduğunu veya işlemin her zaman yetkili olduğunu göstermez. Kullanıcı hesabı kapatılmışsa, rolü değişmişse ya da token çalınmışsa ek oturum iptali ve sunucu tarafı kontrolü gerekebilir.

JWT ile ilgili temel kararlar​

Aşağıdaki ayrım, JWT’nin hangi amaçla kullanılacağını belirlemede yardımcı olur:

Sık yapılan hatalar​

En ciddi hatalardan biri token’ı decode edip imzayı doğrulamadan yetki vermektir. Saldırgan payload’ı değiştirebilir ve uygulama yalnızca okunan değere güveniyorsa yetki yükseltebilir. Algoritmayı token’ın bildirdiği değere koşulsuz bırakmak, anahtarı uygulama koduna gömmek, süresiz token üretmek ve token’ı URL parametresinde taşımak da kaçınılması gereken uygulamalardır.

JWT’yi seçmeden önce iptal gereksinimini belirleyin. Her token’ın anında geçersiz kılınması gerekiyorsa yalnızca JWT’ye güvenmek yerine sunucu tarafı oturum durumu, token sürümü veya iptal kontrolü ekleyin. Sonraki adım, kullandığınız kütüphanenin varsayılan doğrulamasına güvenmek yerine doğrulanan algoritma ve zorunlu claim’leri açıkça tanımlayıp başarısız tüm kontroller için ortak bir ret akışı oluşturmaktır.

Sık sorulan sorular​

JWT ile OAuth aynı şey midir?​

JWT veri taşıma biçimidir; OAuth yetkilendirme çerçevesidir. OAuth access token’ı JWT olabilir veya yalnız sunucunun anlamlandırdığı opak bir değer olabilir. Üç parçalı bir metin görmek akışın OAuth veya doğru tasarlanmış olduğunu kanıtlamaz.

İmzayı doğrulamak için header içindeki anahtar adresine güvenebilir miyim?​

Güvenilmeyen token’ın seçtiği uzak adresi körlemesine çağırmayın. Algoritma ve anahtar kaynağı uygulamanın güvenilen issuer yapılandırmasından gelmelidir; kid gibi alanlar yalnız bu güven sınırında anahtar seçmeye yardımcı olur. Doğrulama kütüphanesinin izin verilen algoritma ve claim koşullarını açıkça ayarlayın.