JWT (JSON Web Token) Nedir?

Yapısı: header.payload.signature

Bir JWT, Base64url ile kodlanmış üç parçanın noktayla birleştirilmesinden oluşur. Kodlanmış hâli xxxxx.yyyyy.zzzzz biçiminde uzun bir metindir; çözüldüğünde parçalar şöyle görünür:

// Header: algoritma ve token türü
{ "alg": "ES256", "typ": "JWT", "kid": "2026-anahtar-1" }

// Payload: iddialar (claims)
{
  "iss": "https://auth.example.com",
  "sub": "user_123",
  "aud": "https://api.example.com",
  "iat": 1767222000,
  "exp": 1767225600,
  "scope": "invoices:read"
}

// Signature
ECDSA_SHA256( base64url(header) + "." + base64url(payload), ozel_anahtar )

Payload'daki iss (token'ı kimin ürettiği), sub (kimin adına), aud (kimin için), exp (son geçerlilik), nbf (geçerlilik başlangıcı), iat (üretim zamanı) ve jti (benzersiz kimlik) standartta kayıtlı iddialardır (RFC 7519). Zaman değerleri Unix saniyesidir; örnekteki token bir saat geçerlidir. Bunların yanına uygulamaya özgü iddialar eklenebilir.

İmzalı, ama gizli değil

Günlük kullanımda "JWT" denince kastedilen, JWS (JSON Web Signature) biçiminde imzalanmış bir token'dır. Base64url bir şifreleme değil, yalnızca bir kodlamadır: token'ı eline geçiren herkes payload'u okuyabilir. İmza, içeriğin yolda değiştirilmediğini ve token'ı doğru anahtara sahip birinin ürettiğini kanıtlar. İçeriğin gizli kalması gerekiyorsa JWE (JSON Web Encryption) kullanılır; ancak çoğu senaryoda daha basit çözüm, hassas veriyi token'a hiç koymamaktır.

İmzalama için iki yaklaşım vardır. HS256 gibi simetrik algoritmalarda aynı gizli anahtar hem imzalar hem doğrular; doğrulama yapabilen her servis token da üretebilir. RS256 ve ES256 gibi asimetrik algoritmalarda ise yalnızca yetkilendirme sunucusu özel anahtarla imzalar, diğer servisler genellikle bir JWKS adresinden yayımlanan açık anahtarla doğrular. Birden fazla servisin token doğruladığı mimarilerde asimetrik imza daha güvenli bir varsayılandır.

Doğrulama adımları

1. İmzayı, sizin belirlediğiniz algoritma listesine göre doğrulayın; token'ın header'ındaki alg değerine güvenmeyin.
2. exp ve varsa nbf değerlerini, birkaç saniyelik saat kayması payıyla kontrol edin.
3. iss değerinin beklenen yayıncı, aud değerinin sizin servisiniz olduğundan emin olun.
4. Ancak bundan sonra kapsam ve rol gibi iddialara bakarak yetkilendirme kararı verin.

Sık yapılan hatalar

• alg: none kabul etmek: Standart, imzasız token'lar için none değerini tanımlar. Bunu kabul eden bir kütüphane ya da yapılandırma, saldırganın imzayı silip payload'u dilediği gibi değiştirmesine izin verir. RS256 açık anahtarının HS256 sırrı gibi kullanıldığı "algoritma karışıklığı" saldırısı da aynı kökten gelir. Bu tuzaklar JWT en iyi uygulamalar belgesinde (RFC 8725) ayrıntılı anlatılır.
• Hassas veri taşımak: T.C. kimlik numarası, e-posta, iç sistem bilgileri gibi veriler payload'a yazılmamalıdır; token loglara, tarayıcı geçmişine ve üçüncü taraf araçlara sızabilir.
• Uzun ömür ve iptal edilememe: Sunucu durumu tutmayan bir JWT, süresi dolmadan geri alınamaz. Erişim token'larını dakikalar mertebesinde kısa tutmak, refresh token'ları her kullanımda yenilemek (rotation) ya da jti üzerinden bir engelleme listesi tutmak gerekir. Anında oturum kapatma şartsa, klasik sunucu oturumu daha uygun olabilir.
• Zayıf HS256 sırrı: Kısa ya da tahmin edilebilir bir sır, ele geçirilen tek bir token üzerinden çevrimdışı kaba kuvvetle bulunabilir.
• Token'ı localStorage'da tutmak: Sayfadaki bir XSS açığı token'ı doğrudan okuyabilir. HttpOnly çerez bu riski azaltır, ama bu kez CSRF önlemlerini gerektirir.

Nerede iyi bir seçim?

JWT, OAuth erişim token'ları, OpenID Connect ID token'ları ve servisler arası çağrılar gibi, alıcının her istekte merkezi bir sunucuya sormadan doğrulama yapmasının değerli olduğu durumlarda güçlüdür. Tek bir sunucunun arkasında çalışan klasik bir web uygulamasında ise kimlik doğrulama sonrası oturumu sunucuda tutmak çoğu zaman daha basit ve daha kolay yönetilir.