JWT: JSON Web Token nedir, yapısı ve kullanımı

JWT Nedir?

JSON Web Token (JWT), taraflar arasında JSON nesnesi olarak bilgi iletmek için kompakt ve kendi kendine yeten bir yol tanımlayan açık bir standarttır (RFC 7519). JWT'deki bilgilere claims denir — özne (kullanıcı) ve ek nitelikler hakkında beyanlar. Her claim bir anahtar-değer çiftidir: kullanıcı tanımlayıcısı, rol, sona erme süresi, yayıncı.

JWT'nin kendi kendine yeten olarak adlandırılmasının nedeni, doğrulama için gereken tüm bilgilerin token'ın içinde olmasıdır. Sunucu, token'ın geçerliliğini doğrulamak için bir veritabanına veya harici depolamaya erişmek zorunda değildir — yalnızca imzayı kontrol etmesi yeterlidir. Bu özellik, JWT'yi dağıtık sistemler ve birden çok hizmetin paylaşılan oturum deposu olmadan istekleri doğrulaması gereken mikro hizmet mimarileri için ideal hale getirir.

Auth0, 2025'e göre, mobil ve web uygulamalarının %65'inden fazlası API kimlik doğrulaması için birincil token biçimi olarak JWT kullanmakta ve opak tokenlar ile oturum tanımlayıcılarını geride bırakmaktadır.

JWT Yapısı: header, payload ve signature

JWT, noktalarla ayrılmış üç bölümden oluşur: header.payload.signature. Her bölüm Base64url kodlu bir JSON'dur. Her bölümü ayrıntılı olarak inceleyelim.

Header — algoritma ve token türü

Header iki zorunlu alan içerir: alg (algorithm — imza algoritması) ve typ (type — token türü, her zaman “JWT”). Algoritma simetrik (HS256 — SHA-256 ile HMAC) veya asimetrik (RS256 — SHA-256 ile RSA, ES256 — P-256 ile ECDSA) olabilir. Asimetrik algoritmalar, istemcinin gizli anahtara sahip olmadan imzayı doğrulamasına izin verdikleri için tercih edilir.

Kodu çözülmüş bir header örneği:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-1"
}

Payload — claims ve veriler

Payload, claims içerir — özne hakkında beyanlar. Claims üç türe ayrılır: kayıtlı (iss, sub, aud, exp, nbf, iat, jti), genel (geliştirici tarafından IANA Kaydında tanımlanan) ve özel (taraflar arasında kararlaştırılan). sub (subject) benzersiz kullanıcı tanımlayıcısıdır. exp (expiration) token'ın sona erme zaman damgasıdır. iss (issuer) token'ın yayıncısıdır.

{
  "sub": "user-abc-123",
  "iss": "https://auth.example.com",
  "aud": "my-mobile-app",
  "exp": 1812345678,
  "iat": 1812342078,
  "role": "premium_user"
}

Signature — bütünlük doğrulaması

Signature, gizli veya özel anahtar kullanılarak header ve payload'ın birleştirilmesine imza algoritması uygulanarak oluşturulur. Formül: HMAC için HMACSHA256(base64UrlEncode(header) + “.” + base64UrlEncode(payload), secret) veya asimetrik algoritma için RSASHA256(...). Alıcı imzayı aynı şekilde hesaplar ve alınan imzayla karşılaştırır — eşleşirlerse veriler değiştirilmemiştir.

JWT Nasıl Çalışır: oluşturma ve doğrulama

JWT ile çalışma akışı iki aşamadan oluşur: kimlik doğrulama sunucusu tarafından token oluşturma (yayınlama) ve istemci veya kaynak sunucu tarafından token doğrulama. Kimlik doğrulama sunucusu, kullanıcının kimlik bilgilerini alır, claims içeren bir payload oluşturur ve imzalar. Ortaya çıkan JWT, oturum açma isteğine yanıt olarak veya OAuth 2.0 / OpenID Connect yanıt gövdesinde istemciye gönderilir.

Mobil kimlik doğrulamada JWT

Mobil uygulamalarda JWT şu şekilde kullanılır: başarılı oturum açma işleminden sonra kullanıcı, JWT biçiminde bir erişim token'ı alır. Uygulama bunu güvenli bir depolama alanında (iOS'ta Keychain, Android'de EncryptedSharedPreferences) saklar. Her API isteğinde uygulama Authorization: Bearer <token> başlığını ekler. API sunucusu JWT imzasını doğrular, claims'leri çıkarır ve bunlara dayanarak erişim kararları alır — veritabanını sorgulamadan.

Google Codelabs, 2025'e göre, Firebase Authentication'da JWT kullanımı, oturum tokenlarına kıyasla kimlik doğrulama sunucusuna yapılan istek sayısını %40–60 oranında azaltır, çünkü veriler her mikro hizmette yerel olarak doğrulanır. Bu, gecikmenin her milisaniyesinin kullanıcı deneyimini etkilediği yüksek yük mimarileri için özellikle önemlidir. Dakikada 50.000 istekte, JWT'ye geçiş, iç sorgulama isteklerini işleyen 10 sunucu örneğine kadar tasarruf sağlayabilir.

JWT vs Session Token

JWT ve Session Token aynı sorunu çözer — istek kimlik doğrulaması — ancak mimaride temel olarak farklılık gösterir. Session Token, sunucuda depolanan oturum verilerine başvuran rastgele bir tanımlayıcı dizedir (durum bilgili). JWT, tüm verileri kendi içinde barındıran kendi kendine yeten bir tokendır (durumsuz).

JWT'nin Avantajları ve Dezavantajları

JWT dağıtık sistemlerde kazanır: mikro hizmetler, paylaşımlı depo olmadan token'ı yerel olarak doğrulayabilir. Örneğin, beş mikro hizmetten oluşan bir mimaride, her hizmet JWT'yi ağ çağrısı olmadan 1–2 ms'de doğrularken, session token her istekte merkezi bir Redis sorgusu gerektirir ve 10–30 ms gecikme ekler. Ancak JWT'yi iptal etmek zordur — bir kez yayınlandıktan sonra süresi dolana kadar geçerlidir. Session Token, DB'den veya Redis'den kaydı silerek kolayca iptal edilebilir.

Mobil uygulamalar için, kısa ömürlü (15–30 dakika) JWT ve Yenileme Token'ı ile birleşik bir yaklaşım, performans ve güvenlik arasında bir denge sağlar. JWT API erişimi için kullanılırken, yenileme token'ı (genellikle opak) yeni JWT'ler almak için kullanılır. Bir JWT tehlikeye girerse, saldırgan 15–30 dakika boyunca erişime sahip olur; bir yenileme token'ı tehlikeye girerse, oturum döndürme ve yeniden kullanım algılama yoluyla engellenir.

JWT Güvenliği

JWT'nin güvenliği doğru uygulamaya bağlıdır. En yaygın güvenlik açığı “alg none” saldırısıdır: saldırgan token'ın header'ını “alg”: “none” olarak değiştirir ve sunucu algoritmayı doğrulamadan sahte token'ı kabul eder. Koruma: header'daki algoritmanın beklenenle (RS256, ES256) eşleştiğini her zaman doğrulayın ve alg: none içeren tokenları reddedin.

Yaygın Güvenlik Açıkları

JWT güvenlik açıkları ayrıca şunları içerir: HMAC için zayıf gizli anahtar (dakikalar içinde kaba kuvvet), özel anahtar sızıntısı (sunucu adına herhangi bir veriyi imzalama), payload'da hassas veri depolama (JWT şifrelemez, yalnızca imzalar), JWK header enjeksiyon saldırısı (özel genel anahtar enjekte etme). Güvenilir kütüphanelerin kullanılması — Nimbus JOSE + JWT, jjwt (io.jsonwebtoken), PyJWT — bu güvenlik açıklarının istismar edilme riskini azaltır.

Ek bir güvenlik önlemi JWK Thumbprint'tir (RFC 7638): header'daki bir parmak izi (thumbprint) aracılığıyla token'a genel bir anahtar bağlama. Sunucu her istemci için beklenen parmak izini saklarsa, JWK header enjeksiyonu imkansız hale gelir — sunucu, kayıtlı olanla eşleşmeyen herhangi bir anahtarı reddeder. OAuth Security Workshop 2025, finansal ve tıbbi uygulamalarda kullanılan tüm JWT'ler için JWK Thumbprint'i zorunlu koruma olarak önermektedir.

Kod Örneği: Kotlin'de JWT ile Çalışmak

jjwt kütüphanesi (auth0/java-jwt), bir Android uygulamasında sadece birkaç satırda JWT oluşturmayı ve doğrulamayı sağlar. Aşağıdaki örnekte, sunucu sub ve role ile bir token oluşturur ve istemci imzayı doğrular. Sunucuda gizli anahtarın güvenli bir şekilde saklanması için ortam değişkenleri veya HSM (Donanım Güvenlik Modülü) kullanın — anahtarı kodda veya yapılandırma dosyasında saklamak ciddi bir güvenlik hatasıdır.

JWT Oluşturma

val secret = "my-256-bit-secret-key-here"
val token = JWT.create()
    .withSubject("user-abc-123")
    .withIssuer("auth.example.com")
    .withClaim("role", "premium_user")
    .withExpiresAt(Date(System.currentTimeMillis() + 3600000))
    .sign(Algorithm.HMAC256(secret))

// Token'ı istemciye gönderme
println("JWT: $token")

JWT Doğrulama

fun verifyToken(token: String): Boolean {
    return try {
        val decoded = JWT.require(Algorithm.HMAC256(secret))
            .withIssuer("auth.example.com")
            .build()
            .verify(token)
        // İmza geçerli, claims çıkarıldı
        println("Subject: ${decoded.subject}")
        true
    } catch (e: Exception) {
        println("Token geçersiz: ${e.message}")
        false
    }
}