JWT Parser Rehberi: JSON Web Token’ları Güvenli Şekilde Çözme, Doğrulama ve İnceleme

Üretim ortamında kimlik doğrulamanız aniden bozuldu. Kullanıcılar “Invalid Token” hatası alıyor ve nedenini hızlıca çözmeniz gerekiyor. JWT’yi açtığınızda anlamsız bir dizge karşısındasınız: noktalarla ayrılmış üç blok rastgele karakter. Veri orada duruyor, ancak bir parser olmadan okuyamıyorsunuz.

Bir JWT Parser, RFC 7519 standardını izleyerek bir JSON Web Token’ın üç bölümünü — Header, Payload ve Signature — ayrıştırır. Nisan 2026 itibarıyla bu parserlar Base64URL ile kodlanmış veriyi çözer ve tokenın değiştirilmediğinden emin olmak için imzaları secret veya public key kullanarak doğrular; böylece “alg: none” saldırısı gibi tehditleri engeller.

Bir JWT Parser Aslında Ne Yapar?

JWT parsera bir çevirmen olarak düşünün. Uzun, anlaşılmaz bir dizgeyi alır ve tekrar okunabilir JSON nesnelerine dönüştürür. Bu, modern uygulamalarda kullanıcı kimliklerini yönetmek ve veri alışverişini güvence altına almak için temel bir işlemdir.

İçeride parser, tokenı üç bölüme ayıran iki noktayı (.) bulur:

Bölüm	Amaç	Kodlanmış mı?	Anahtar olmadan okunabilir mi?
Header	Meta veriler: imzalama algoritması (HS256, RS256)	Base64URL	Evet
Payload	Claimler: kullanıcı verisi, son kullanma, roller	Base64URL	Evet
Signature	Orijinalliği kanıtlayan dijital mühür	HMAC/RSA	Hayır — anahtar gerekir

Adım Adım Çözme: İçeride Ne Oluyor?

Gerçek bir token üzerinden ilerleyelim. Şu örnek JWT’yi ele alın:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4iLCJpYXQiOjE3MDAwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Adım 1: Noktalardan böl

[0] eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
[1] eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4iLCJpYXQiOjE3MDAwMDAwMDB9
[2] SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Adım 2: [0] numaralı bölümü (Header) Base64URL ile çöz

{
  "alg": "HS256",
  "typ": "JWT"
}

Adım 3: [1] numaralı bölümü (Payload) Base64URL ile çöz

{
  "sub": "1234567890",
  "name": "John",
  "iat": 1700000000
}

Adım 4: [2] numaralı bölümü (Signature) doğrula — secret key gerektirir

Parser, Base64URL ile kodlanmış header + “.” + payload dizgesini alır ve secret kullanarak bir HMAC-SHA256 hesaplar. Sonuç [2] numaralı bölümle eşleşirse token orijinaldir.

Kritik Güvenlik Notu: Base64URL Şifreleme Değildir

Yeni geliştiriciler için yaygın bir tuzak, kodlanmış header ve payloadın şifrelendiğini varsaymaktır. Şifrelenmemiştir. JustUse.me’nin belirttiği gibi, Base64URL kodlaması yalnızca JSON’u URL’ler ve headerlar üzerinden güvenle gönderilebilir hale getirir. Tokena sahip olan herkes, bir parola veya anahtar olmadan payloadı çözebilir.

Asla hassas verileri (parolalar, SSN, API keyler) bir JWT payloadında depolamayın. Tokenı ele geçiren herkes tarafından görülebilir.

İmza Doğrulama: Güvenlik Kapısı

Herkes bir tokenın verisini okuyabilirken, sisteminizi gerçekten güvende tutan şey imza doğrulamasıdır. Bir JWT parser yalnızca bilgi okumaz — verinin nereden geldiğini kanıtlar.

Parser, header, payload ve bir anahtar kullanarak imzayı yeniden hesaplar, sonra sonucun token üzerindeki imzayla eşleşip eşleşmediğini kontrol eder. Eşleşmezlerse, token değiştirilmiştir.

İki Algoritma Ailesi

Algoritma	Anahtar Türü	Nasıl Çalışır	Yaygın Kullanım Senaryosu
HS256 (HMAC)	Simetrik — imzalama ve doğrulama için aynı secret key	Her iki taraf bir secret paylaşır	Tek servis kimlik doğrulaması, bir ekip içindeki mikro servisler
RS256 (RSA)	Asimetrik — private key imzalar, public key doğrular	Gönderen private key’i elinde tutar; public key’e sahip olan herkes doğrulayabilir	OAuth2 sağlayıcıları, üçüncü taraf API entegrasyonları
ES256 (ECDSA)	Asimetrik — RSA ile aynı model ama eliptik eğrilerle	Daha küçük anahtarlar, daha hızlı doğrulama	Mobil uygulamalar, performansa duyarlı servisler

“alg: none” Saldırısı

Bu, en tehlikeli JWT zafiyetlerinden biridir. Saldırgan, headerı değiştirerek "alg": "none" iddiasında bulunur ve imzayı kaldırır. Zayıf uygulanmış bir parser bunu kabul edebilir ve tokenı herhangi bir doğrulama olmadan geçerli olarak değerlendirebilir.

Savunma: Parserınız, algoritma “none” olan veya beklediğiniz algoritmayla eşleşmeyen tüm tokenları açıkça reddetmelidir. Apify JWT aracını geliştiren Stas Persiianenko, tokenların tasarım gereği şeffaf olduğunu ancak güvenliklerinin parserın imzasız veya değiştirilmiş tokenları katı bir şekilde reddetmesine bağlı olduğunu vurgular.

decoded = jwt.decode(token, key, algorithms=None)  # ASLA bunu yapmayın

decoded = jwt.decode(token, key, algorithms=["HS256"])

Standart JWT Claimleri: Her Alanın Anlamı

Bir JWT parser, payloaddan “claim”leri çıkarır. Bunlar, sistemler arası uyumluluk için JOSE (JSON Object Signing and Encryption) çerçevesini izler.

Claim	Tam Adı	Amaç	Örnek Değer
iss	Issuer	Tokenı kim verdi	"auth.example.com"
sub	Subject	Tokenın temsil ettiği kullanıcı veya varlık	"user:12345"
aud	Audience	Tokenın hedeflenen alıcısı	"api.example.com"
exp	Expiration Time	Tokenın ne zaman geçersiz hale geldiği	1700000000 (Unix timestamp)
iat	Issued At	Tokenın ne zaman oluşturulduğu	1699999999
nbf	Not Before	Token bu zamandan önce geçerli değil	1699999999
jti	JWT ID	Token için benzersiz tanımlayıcı	"a1b2c3d4"

Asimetrik imzalar kullanıldığında, parserlar genellikle bir JWK (JSON Web Key) — bir public key’i temsil eden JSON yapısı — referans alır. Parser, tokenı doğrulamak için doğru JWK’yi issuerın meta veri endpointinden otomatik olarak çeker.

Uygulama: Üretim için Gerçek Kod

PHP ile lcobucci/jwt

PHP ekosisteminin standardı lcobucci/jwt’dir. Packagist verileri, Nisan 2026 itibarıyla 322 milyondan fazla kurulum gösteriyor; bu da onu Laravel ve Symfony projeleri için ilk tercih yapıyor.

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Signer\Key\InMemory;

$config = Configuration::forSymmetricSigner(
    new Sha256(),
    InMemory::plainText('your-secret-key')
);

// Parsing and validating a token
$token = $config->parser()->parse($jwtString);

// Verify constraints: expiration, issuer, etc.
$constraints = [
    new \Lcobucci\JWT\Validation\Constraint\IssuedBy('auth.example.com'),
    new \Lcobucci\JWT\Validation\Constraint\PermittedFor('api.example.com'),
    new \Lcobucci\JWT\Validation\Constraint\SignedWith(
        $config->signer(),
        $config->signingKey()
    ),
];

$isValid = $config->validator()->validate($token, ...$constraints);

Hono (Edge/Serverless) ile Web Crypto

Hafif edge uygulamaları için Hono JWT Helper, hızlı soğuk başlangıçlar ve minimal bağımlılıklar istediğiniz serverless platformlar için ideal, minimal bir decode() fonksiyonu sunar.

import { jwt } from 'hono/jwt'

// Middleware to verify JWT on every request
app.use('/api/*', jwt({ secret: 'your-secret' }))

// Access decoded claims in your handler
app.get('/api/profile', (c) => {
  const payload = c.get('jwtPayload')
  return c.json({ user: payload.sub })
})

MCP ile AI Destekli JWT Analizi

2026’ya gelindiğinde, Model Context Protocol (MCP); Claude Code veya Cursor gibi AI asistanlarının JWT araçlarıyla doğrudan konuşmasını sağlar. Bir MCP server kurun ve bir geliştirici, bir AI’dan “Bu loglardaki tüm JWT’lerde son kullanma hatalarını kontrol et” isteyebilir — ajan ayrıştırmayı komut satırı üzerinden halleder.

Apify’ya göre, toplu işleme 2026 itibarıyla 10.000 token başına yaklaşık $11.50 maliyetinde. Bu otomasyon, AI ajanlarının süresi dolmuş tokenları bulmasına ve uygulamanın güvenlik ayarları için anında kod düzeltmeleri önermesine olanak tanır.

Sonuç

Bir JWT parser, yalnızca hata ayıklama kolaylığı değil — hayati bir güvenlik kontrol noktasıdır. İmza kontrolleri yoluyla tokenların orijinal olmasını ve claim doğrulaması yoluyla geçerli olmasını sağlar. En çok önem taşıyan iki kuralı unutmayın: Base64URL şifreleme değildir, bu yüzden asla payloada secret koymayın. Ve “alg: none” saldırılarını önlemek için her zaman izin verilen algoritmaları açıkça belirtin.

Üretim uygulamaları için kendi parserınızı yazmak yerine lcobucci/jwt veya Hono’nun JWT helperı gibi kanıtlanmış kütüphaneleri kullanın. Hata ayıklama ve toplu analiz için AI destekli MCP araçları, güvenlik denetimlerini otomatik ve kapsamlı tutmanın modern yoludur.

SSS

Tarayıcımda bulduğum bir JWT tokenı çözmek yasal mı?

Evet, tamamen yasal. JWT’ler şeffaf olacak şekilde tasarlanmıştır — header ve payload taşımak için kodlanmıştır, gizlilik için şifrelenmemiştir. Tokena sahip olmak, claimlerindeki verilere erişiminiz olduğu anlamına gelir. Ancak tokenlar kişisel bilgi içerdiğinde GDPR gibi yerel veri koruma yasalarına her zaman uyun.

Neden yeni oluşturduğum bir token için JWT parser isExpired: true gösteriyor?

Bu genellikle tokenı oluşturan sunucu ile onu ayrıştıran sistem arasındaki saat kayması (clock drift) nedeniyle olur. İki sistemin saatleri (UTC/NTP üzerinden) senkronize değilse, exp veya nbf claimleri geçersiz görünebilir. Bunu, her iki sistemin de zaman senkronizasyonu için NTP kullandığından emin olarak veya ayrıştırma kütüphanenizde küçük kaymaları telafi için küçük bir “leeway” (genellikle 60 saniye) ekleyerek düzeltin.

Secret veya public key olmadan bir JWT’yi çözebilir miyim?

Evet, Header ve Payload yalnızca Base64URL ile kodlanmış JSON olduğu için her zaman bir anahtar olmadan çözebilir ve okuyabilirsiniz. Ancak, ilgili secret (HS256 için) veya public key (RS256 için) olmadan İmzayı doğrulayamaz veya verinin orijinal olduğuna güvenemezsiniz. Doğrulama olmadan, veriyi doğrulanmamış ve potansiyel olarak değiştirilmiş olarak değerlendirin.

“alg: none” saldırısı nedir ve nasıl önlerim?

“alg: none” saldırısı, token headerında belirtilen algoritmayı doğrulamadan kabul eden parserları istismar eder. Saldırgan headerı "alg": "none" olarak değiştirir ve imzayı kaldırır; böylece savunmasız bir parserı tokenı geçerli olarak kabul etmesi için kandırır. Bunu, doğrulama kodunuzda her zaman izin verilen algoritmaları açıkça belirterek önleyin — asla “none” kabul etmeyin veya tokenın hangi algoritmanın kullanılacağını dikte etmesine izin vermeyin.