JWT pratik kullanımı

JSON Web Token (JWT), dagitik sistemlerde kimlik dogrulama ve yetkilendirme icin en yaygın tasiyici formattir. Stateless dogasi, mikroservisler arasi cagrilarda ve mobil istemcilerde oturum yönetimini basitlestirir; ancak JWT'nin kendisi güvenlik saglamaz. Yanlış algoritma seçimi, uzun omurlu access token, refresh token'in guvensiz saklanmasi veya imza dogrulamasinin atlanmasi ciddi ihlallere yol acar. Bu makale, JWT'yi üretim ortaminda güvenli ve performansli kullanmak icin gerekli teknik kararları derinlemesine inceler.

JWT yapisinin teknik anatomisi

Bir JWT uc bolumden olusur: header, payload ve signature. Header algoritma ve token tipini belirtir; payload claim'leri tasir; signature header ve payload'in imzalanmis halidir. Standart claim'ler arasinda iss (issuer), sub (subject), aud (audience), exp (expiration), nbf (not before) ve iat (issued at) bulunur. Özel claim'ler rol, tenant veya scope bilgisi tasiyabilir; ancak JWT payload base64url ile kodlanir, sifrelenmez — hassas veri tasimamak temel kuraldir.

// Ornek header + payload (imza haric)
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "2026-prod-key-1"
}
{
  "iss": "https://auth.example.com",
  "sub": "user-48291",
  "aud": "api.example.com",
  "exp": 1710003600,
  "iat": 1710000000,
  "scope": "orders:read orders:write"
}

Imzalama algoritmasi seçimi

HS256 (HMAC-SHA256) simetrik bir anahtar kullanır; imzalayan ve dogrulayan ayni secret'i bilir. Tek servisli monolitlerde basit görünür, fakat mikroservislerde secret paylasimi lateral movement riskini artirir. RS256 veya ES256 asimetrik anahtar kullanır: auth servisi private key ile imzalar, API servisleri yalnizca public key ile dogrular. JWKS endpoint uzerinden public key dagitimi, key rotation'i kolaylastirir. alg: none saldirisina karşı kutuphane ayarlarinda algoritma whitelist zorunludur.

• Asimetrik imza: Auth servisi dışında private key bulunmaz; API compromise token uretemez.
• Key ID (kid): Rotation sirasinda birden fazla public key aktif olabilir; dogrulayici doğru anahtari secer.
• Minimum algoritma: HS256 yerine RS256/ES256 tercih edin; HS256 yalnizca kapali ağ icinde kisa omurlu servis token'lari icin dusunulebilir.

Access token ve refresh token ayrimi

Access token kisa omurlu olmalidir: tipik olarak 5–15 dakika. Uzun omurlu access token calindiginda saldirgan uzun sure yetkili kalir. Refresh token daha uzun omurlu olabilir ancak güvenlik gereksinimleri farklidir: refresh token yalnizca auth servisine gonderilir, HttpOnly ve Secure cookie'de veya mobilde Keychain/Keystore'da saklanir. Refresh token rotation her kullanımda yeni refresh token üretir; eski token tek kullanimlik olur. Calinti refresh token tekrar kullanıldığında tüm oturum ailesi iptal edilir (reuse detection).

Token baglama (binding)

Refresh token'i cihaza veya oturuma baglamak calinti token'in baska ortamda kullanilmasini zorlastirir. client_id, DPoP (Demonstrating Proof-of-Possession) veya mTLS ile sender-constrained token modelleri OAuth 2.1 yonunde standartlastirilmaktadir. Web uygulamalarinda PKCE, authorization code flow'da code interception saldirisini onler.

Dogrulama pipeline'i

Her API isteginde JWT dogrulamasi su adimlari icermelidir:

1. Imza dogrulama (doğru public key ve algoritma ile)
2. exp ve nbf kontrolu (clock skew toleransi: 30–60 saniye)
3. iss ve aud beklenen degerlerle eslesme
4. Token revocation listesi veya introspection (kritik iptaller icin)
5. Scope veya rol bazli yetki kontrolu (RBAC/ABAC katmanı)

// ASP.NET Core JWT Bearer — temel dogrulama ayarlari
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://auth.example.com";
        options.Audience = "api.example.com";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromSeconds(30),
            ValidAlgorithms = new[] { SecurityAlgorithms.RsaSha256 }
        };
    });

JWKS cache ve performans

Public key her istekte auth servisinden cekilmemelidir. JWKS endpoint cevabi uygun TTL ile cache'lenir; kid degistiginde cache invalidate edilir. Yüksek trafikli API'lerde local cache + background refresh, auth servisine bagimliligi azaltir. Dogrulama başarısız oldugunda farklı hata siniflari (expired, invalid signature, wrong audience) loglanir; ancak token içeriği log'a yazilmamalıdır.

Güvenlik anti-pattern'leri

• JWT'yi session store yerine kullanmak: Stateless avantaji kaybolur; her istekte DB sorgusu yapilir.
• Payload'a PII koymak: Token browser'da veya log'larda gorulebilir.
• Logout = token silme: Client token'i siler ama sunucu dogrulamaya devam eder; blacklist veya kisa omur sart.
• Secret'i client-side'da imzalamak: SPA'da HS256 secret asla bulunmamali.

Revocation ve oturum iptali

Tam stateless modelde anlik iptal zordur. Pratik çözümler: cok kisa access token omru, refresh token rotation, token version claim (kullanıcı şifre degistiginde version artirilir), veya Redis tabanli blacklist (kritik iptaller icin). Yüksek güvenlik gerektiren islemlerde step-up authentication veya kisa omurlu tek kullanimlik token (step-up token) uygulanir.

Cross-service trust

Servisler arasi cagrida service account JWT veya mTLS tercih edilir. Kullanıcı JWT'sini downstream servise iletmek (token passthrough) yetki genislemesine yol acabilir; gateway token'i validate edip dahili identity context olusturmalidir. Istek basina yeni kisa omurlu service token üretmek blast radius'u kucultir.

Test ve güvenlik dogrulama

JWT entegrasyon testlerinde expired token, yanlış audience, degistirilmis payload (algorithm confusion), ve kid injection senaryolari otomatik test edilmelidir. OWASP JWT Cheat Sheet ve RFC 8725 (JWT Best Current Practices) checklist olarak kullanılabilir. Penetrasyon testlerinde jwt_tool ile imza zafiyetleri taranir.

Operasyonel izleme

Auth metrikleri: token issuance rate, refresh failure rate, invalid signature spike, ortalama token omru. Ani refresh failure artisi credential stuffing veya calinti refresh token kullanimina isaret edebilir. Rate limiting auth endpoint'lerinde zorunludur; brute force ve token endpoint abuse onlenir.

JWT pratik kullanımı, doğru algoritma, kisa omurlu access token, güvenli refresh token yönetimi ve katmanli dogrulama pipeline'i ile baslar. Stateless mimari avantaj sağlar; ancak iptal, rotation ve scope kontrolu bilincli tasarlanmazsa güvenlik borcu hizla birikir. Üretim sistemlerinde asimetrik imza, JWKS cache, refresh rotation ve reuse detection birlikte uygulandiginda JWT hem performansli hem de savunulabilir bir kimlik tasiyicisi haline gelir.

Multi-tenant ve claim tasarımı

Cok kiracili sistemlerde tenant_id claim'i zorunludur; API her istekte tenant izolasyonunu claim uzerinden dogrular. Claim setini minimal tutun: gereksiz claim token boyutunu artirir ve her istekte taşıma maliyeti oluşturur. Rol bilgisi JWT'de tasiyorsa rol degisikligi token yenilenene kadar gecikir; kritik sistemlerde rol kontrolunu merkezi policy servisine birakmak daha güncel sonuç verir. Custom claim isimleri namespaced olmali (https://example.com/roles) cakisma onlenir.

Edge case'ler ve saat senkronizasyonu

Distributed sistemlerde NTP drift token gecerlilik penceresini etkiler. ClockSkew makul tutulmali; asiri geniş skew expired token kabul riski tasir. nbf claim'i gelecekte geçerli token'lar icin kullanılır; scheduled access senaryolarinda faydalidir. Leeway yalnizca dogrulama tarafinda uygulanir; üretim tarafinda kesin exp hesaplanir.

OAuth 2.0 ve OpenID Connect entegrasyonu

JWT çoğu zaman OAuth 2.0 authorization code flow sonucunda ID token veya access token olarak doner. OpenID Connect, ID token'in standart claim setini tanimlar. Resource server yalnizca access token'i kabul etmeli; ID token kullanıcı kimligi icin client tarafinda kalir. Token exchange (RFC 8693) ile downstream servisler kendi scope'unda yeni token alir; kullanıcı token'i servisler arasi tasınmaz. Authorization server metadata discovery (/.well-known/openid-configuration) issuer, JWKS URI ve desteklenen grant type bilgisini otomatik sağlar.

Güvenlik basliklari ve transport

JWT HTTP Authorization header'da Bearer semasi ile iletilir; URL query string'de token tasimak access log sızıntisi riski tasir. Cookie tabanli JWT kullanıldığında SameSite=Strict veya Lax, HttpOnly ve Secure bayraklari zorunludur. CSRF korumasi state-changing isteklerde anti-forgery token veya double-submit cookie ile tamamlanir. TLS 1.2+ tüm token iletiminde sarttir; mixed content ve downgrade saldirilarina karşı HSTS uygulanir.