JWT Nedir? JSON Web Token'lara Açık Bir Rehber

JWT basitçe

Bir JWT (JSON Web Token), sistemler arasında taşınabilen, bilgi (genellikle bir kullanıcı veya oturum hakkında) temsil eden kompakt, URL-uyumlu bir dizgedir. Genellikle eyJ... ile başlayan uzun bir değer görürsünüz ve Authorization: Bearer \u003ctoken\u003e gibi bir HTTP header'ında gönderilir.

Neden token kullanılır?

Geleneksel girişler genellikle sunucu oturumlarına (server sessions) dayanır: oturum açtıktan sonra sunucu oturum verisini saklar ve tarayıcıya bir oturum kimliği cookie'si verir. Her istek o cookie'yi içerir ve sunucu oturumu arar.

Token tabanlı kimlik doğrulama ile sunucu her kullanıcının isteği için durum saklamak zorunda kalmaz. Bunun yerine istemci bir token (ör. JWT) tutar ve API çağrılarıyla birlikte gönderir. Bu, API'ler için popülerdir çünkü:

• birden çok servis arasında iyi çalışır (API geçitleri, mikroservisler)
• API'leri doğrudan çağıran mobil ve tek sayfa uygulamalar (SPA) için uygundur
• sunucular arasında paylaşılan oturum depolamaya olan ihtiyacı azaltır

Önemli nüans: “durumsuz” demek “hiçbir sunucu tarafı kontrolü yok” anlamına gelmez. Birçok gerçek sistem hâlâ kullanıcı durumunu, anahtar rotasyonunu veya iptal mekanizmalarını kontrol eder.

Kimlik doğrulama vs yetkilendirme (düz Türkçe)

• Kimlik doğrulama (authentication) sorar: Sen kimsin? (Oturum açarsınız ve kimliğinizi kanıtlayınız.)
• Yetkilendirme (authorization) sorar: Ne yapmaya izinlisin? (Faturaları okuma, projeleri düzenleme, yönetici sayfalarına erişim vb.)

JWT'ler genellikle kimlik doğrulama kanıtı (oturum açık) ve basit yetkilendirme ipuçları (roller, izinler, scope'lar) taşır—ama sunucunuz yine de yetkilendirme kurallarını uygulamalıdır.

JWT'lerin kullanıldığı yerler

JWT'leri genellikle erişim tokenı olarak şu yerlerde görürsünüz:

• web API'leri
• SPA'lar
• mobil uygulamalar
• OAuth 2.0 veya OpenID Connect (OIDC) kullanan sistemler

JWT yapısı: header, payload ve signature

Bir JWT, her biri base64url ile kodlanmış ve nokta ile ayrılmış üç parçadan oluşan kompakt bir dizgedir:

header.payload.signature

Örnek (kısaltılmış):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNzAwMDAwMDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c…

1) Header

Header, tokenin nasıl oluşturulduğunu açıklar—özellikle imzalama algoritması (ör. HS256, RS256/ES256) ve token türü.

Yaygın alanlar:

• typ: genellikle "JWT" (çoğunlukla göz ardı edilir)
• alg: kullanılan imzalama algoritması
• kid: doğrulayıcının rotasyon sırasında doğru anahtarı seçmesine yardımcı olan anahtar tanımlayıcısı

Güvenlik notu: header'a körü körüne güvenmeyin. Gerçekten kullandığınız algoritmaların bir allowlist'ini uygulayın ve alg: "none" kabul etmeyin.

2) Payload

Payload, kullanıcı ve token bağlamı hakkında "claim" (alan) tutar: kimin için olduğu, kimin oluşturduğu ve ne zaman süresinin dolacağı gibi.

Önemli: JWT'ler varsayılan olarak şifrelenmez. Base64url kodlama tokeni URL-uyumlu yapar; veriyi gizlemez. Tokeni alan herkes header ve payload'u çözebilir.

Bu yüzden parolalar, API anahtarları veya hassas kişisel verileri JWT'ye koymaktan kaçının.

3) Signature

Signature, header + payload'in bir anahtarla imzalanmasıyla oluşturulur:

• HS256: paylaşılan bir gizli anahtar ile imzalanır ve doğrulanır
• RS256/ES256: özel anahtar imzalar; genel anahtar doğrular

İmza bütünlük sağlar: sunucu tokenin değiştirilmediğini ve güvenilir bir imzalayıcı tarafından oluşturulduğunu doğrulayabilir. Bu, gizlilik sağlamaz.

Boyut düşüncesi

Bir JWT her istekle birlikte header ve payload'ı içerdiğinden, daha büyük tokenlar daha fazla bant genişliği ve ek yük demektir. Claim'leri sade tutun ve fazla veri yerine tanımlayıcıları tercih edin.

Payload ve claim'ler: ne koymalı/ne koymamalı

Claim'ler genelde iki kategoriye ayrılır: registered (standart isimler) ve custom (uygulamanıza özel alanlar).

Yaygın registered claim'ler

• iss (issuer): tokeni kim oluşturdu
• sub (subject): tokenin kim hakkında olduğu (çoğunlukla kullanıcı ID'si)
• aud (audience): tokenin hedefi (ör. belirli bir API)
• exp (expiration time): tokenin kabul edilmemesi gereken zaman
• iat (issued at): tokenin oluşturulma zamanı
• nbf (not before): tokenin bu zamandan önce kabul edilmemesi gerekir

Özel claim'ler: az tutun

Hizmetin gerçekten yetkilendirme kararı vermesi için ihtiyaç duyduğu kadar bilgi koyun.

İyi örnekler:

• kararlı bir dahili kullanıcı tanımlayıcısı (user_id)
• küçük bir roller/izinler seti (sürekli güncel tutabiliyorsanız)
• çok kiracılı (multi-tenant) uygulamalarda tenant/organizasyon ID'si

Profil verisini kopyalayan "kolaylık" claim'lerinden kaçının. Bunlar tokeni şişirir, çabuk bayatlar ve token sızarsa etkisini artırır.

JWT payload'ına asla koymamanız gerekenler

Payload okunabildiği için koymayın:

• parolalar, API anahtarları, refresh tokenlar veya herhangi bir gizli değer
• ödeme bilgileri, kimlik numaraları veya hassas kişisel veriler
• tarayıcıdan, proxy'den veya loglardan kopyalanmasını istemeyeceğiniz herhangi bir şey

Hassas bilgi gerekiyorsa, sunucuda saklayın ve token'da sadece bir referans (ör. ID) bulundurun—ya da uygun olduğunda şifreli token formatı (JWE) kullanın.

İmza nasıl çalışır (ve neyi garanti eder)

İmzalama şifreleme değildir.

• İmzalama, bir mektubu mühürlemek gibidir: herkes okuyabilir, ama değiştirilmediğini doğrulayabilir.
• Şifreleme, mektubu bir kutuya kilitlemek gibidir: sadece anahtara sahip olan okuyabilir.

Token verildiğinde sunucu header + payload'i imzalar. Token daha sonra sunulduğunda sunucu imzayı yeniden hesaplar ve karşılaştırır. Bir karakter bile değişse doğrulama başarısız olur ve token reddedilir.

JWT vs OAuth, OpenID Connect ve token türleri

JWT bir token formatıdır. OAuth 2.0 ve OpenID Connect (OIDC) tokenlerin nasıl talep edileceğini, verileceğini ve kullanılacağını tanımlayan protokollerdir.

OAuth 2.0 ve access/refresh tokenlar

OAuth 2.0 esas olarak yetkilendirme ile ilgilidir: bir uygulamanın kullanıcının şifresini paylaşmadan bir API'ye erişmesine izin vermek.

• Access token: bir API'ye izin kanıtı olarak sunulur; JWT veya opak bir token olabilir
• Refresh token: yeni access token almak için daha uzun ömürlü token

Access tokenlar genellikle kısa ömürlüdür (dakikalar). Kısa süre, bir token sızarsa zararını sınırlar.

OpenID Connect (OIDC) ve ID tokenlar

OIDC OAuth 2.0 üzerine kimlik doğrulamayı ekler ve genellikle bir ID token (çoğunlukla JWT) sunar.

• ID token: istemci uygulamanın kullanıcının kimliğini doğrulaması için
• Access token: API'nin istekleri yetkilendirmesi için

Temel kural: ID token'ı bir API çağrısı yapmak için kullanmayın.

Eğer akışlar hakkında daha fazla pratik bilgi isterseniz, şu kaynağa bakın: /blog/jwt-authentication-flow.

Yaygın JWT kimlik doğrulama akışı

Tipik bir akış şöyle işler:

1) Giriş

Kullanıcı (e-posta/parola, SSO vb.) ile oturum açar. Başarılıysa sunucu subject ve expiration gibi temel claim'lerle bir JWT (genellikle bir access token) oluşturur.

2) Token verilmesi

Sunucu tokeni imzalar ve istemciye (web uygulaması, mobil uygulama veya başka bir servis) döner.

3) API çağrıları

Korumalı uç noktalarda istemci JWT'yi Authorization header'ında gönderir:

Authorization: Bearer \u003cJWT\u003e

4) Doğrulama

İstek işlenmeden önce API genellikle şu kontrolleri yapar:

• imza (bütünlük + güvenilir issuer)
• exp (süresi dolmadı)
• iss (beklenen issuer)
• aud (bu API için mi)

Tüm kontroller geçerse API kullanıcıyı kimliklendirilmiş kabul eder ve yetkilendirme kurallarını uygular (ör. kayıt düzeyi izinleri).

5) Saat kayması hakkında kısa not

Sistem saatleri kayabilir; bu yüzden exp ve bazen nbf gibi zaman bazlı claimleri doğrularken küçük bir saat kayması (clock skew) toleransı verilir. Toleransı küçük tutun ki token ömrü gereğinden fazla uzamasın.

JWT'leri güvenli saklama yerleri

Depolama seçimi saldırganların hangi tokenleri çalabileceğini ve bunları ne kadar kolay tekrar kullanabileceğini değiştirir.

Tarayıcı uygulamaları: bellek vs localStorage vs cookie

Bellekte saklama (çeşitli SPA'larda önerilir) erişim tokenını JS state'te tutar. Yenilemede temizlenir ve "sonradan çalma" riskini azaltır; ancak bir XSS açıkken yine okunabilir. Kısa ömürlü access tokenlar ve bir yenileme akışı ile kullanın.

localStorage/sessionStorage kullanımı kolaydır ama risklidir: herhangi bir XSS açığı tokenleri çalabilir. Eğer kullanıyorsanız XSS önlemlerini kesinlikle uygulayın (CSP, output escaping, bağımlılık temizliği) ve token sürelerini kısa tutun.

Güvenli cookie'ler (çoğunlukla web için en güvenli varsayılan) tokenleri HttpOnly cookie'de saklayarak JavaScript'in okumamasını sağlar—bu, XSS ile token hırsızlığını azaltır. Dezavantajı CSRF riskidir, çünkü tarayıcı cookie'leri otomatik olarak gönderir.

Cookie kullanıyorsanız şunları ayarlayın:

• HttpOnly
• Secure (yalnızca HTTPS)
• SameSite=Lax veya SameSite=Strict (bazı çapraz-site akışlar SameSite=None; Secure gerektirebilir)

Ayrıca durum değiştiren istekler için CSRF tokenlerini düşünün.

Mobil uygulamalar: OS güvenli depolamayı tercih edin

iOS/Android'de tokenleri platformun güvenli depolamasında (Keychain / Keystore destekli) saklayın. Düz dosya veya preferences içinde saklamaktan kaçının. Tehdit modeliniz köklü/jailbreak yapılmış cihazları içeriyorsa, çıkarımı mümkün kabul edin ve kısa ömürlü tokenlar ile sunucu tarafı kontrollerine güvenin.

En az ayrıcalık (least privilege)

Bir tokenin yapabileceği şeyi sınırlandırın: minimum scope/claim'ler kullanın, access tokenları kısa ömürlü tutun ve hassas verileri gömmekten kaçının.

Yaygın JWT güvenlik hataları

JWT'ler kullanışlıdır, ancak birçok olay tahmin edilebilir hatalardan kaynaklanır. Bir JWT'yi nakit gibi değerlendirin: onu alan genellikle onu harcayabilir.

1) Çok uzun süreli tokenlar

Token günler veya haftalar boyunca geçerliyse, sızıntı bir saldırgana geniş bir pencere verir.

Access tokenları için mümkün olduğunca kısa süre (dakikalar) tercih edin ve güvenli bir mekanizma ile yenileyin. "Beni hatırla" gerekiyorsa bunu refresh tokenlar ve sunucu tarafı kontrollerle yapın.

2) Issuer ve audience kontrollerini atlamak

Geçerli bir imza tek başına yeterli değildir. iss ve aud doğrulayın ve exp/nbf gibi zaman bazlı claimleri kontrol edin.

3) Çözümlenmiş payloadlara güvenmek

Decode etmek doğrulama değildir. Her zaman sunucuda imzayı doğrulayın ve izinleri sunucu tarafında uygulayın.

4) Algoritma karışıklığı ve anahtar hataları

• Tokenin iddia ettiği algoritmayı olduğu gibi kabul etmeyin. Beklenen algoritmaları allowlist'e alın.
• Simetrik anahtarlar (HS256) ile asimetrik anahtarları (RS256/ES256) karıştırmayın.
• Patlamayı sınırlandırmak için ortam başına ayrı anahtarlar kullanın ve anahtarları döndürün.

5) Tokenin URL'lerde, loglarda ve referrer'larda sızması

JWT'leri sorgu parametresine koymaktan kaçının. Tarayıcı geçmişinde, sunucu loglarında, analiz araçlarında veya referrer başlıklarında yer alabilirler.

Bunun yerine Authorization: Bearer ... kullanın.

6) Anahtar rotasyonu veya iptal planı olmaması

Anahtarların ve tokenların sızabileceğini varsayın. İmza anahtarlarını döndürün, kid kullanarak yumuşak rotasyonu destekleyin ve iptal stratejiniz olsun (kısa süreler + hesap/oturum devre dışı bırakma gibi). Depolama kılavuzu için şu kaynağa bakın: /blog/where-to-store-jwts-safely.

Ne zaman JWT kullanmalı (ve ne zaman kullanmamalı)

JWT'ler faydalıdır, ama otomatik olarak en iyi seçenek değiller. Asıl soru, her istekte veritabanı sorgusu yapmadan doğrulanabilecek kendi içinde yeterli bir tokenten fayda sağlayıp sağlamadığınızdır.

JWT için uygun durumlar

• Büyüyen, durumsuz API'ler: imza + expiry ile yerel doğrulama, her istek için oturum araması gerekmez
• Birden çok servis / mikroservis: ortak doğrulama kuralları ve genel anahtar dağıtımı
• SPA'lar ve mobil uygulamalar: istemcilerin doğrudan API çağrısı yaptığı durumlar
• Kısa ömürlü erişim tokenları: çalınmanın etkisini azaltır

JWT'nin uygun olmadığı durumlar

• Anında iptal zorunluysa: her yerde hemen çıkış gerektiriyorsa oturumlar daha basit olabilir
• Hassas veri taşınması gerekiyorsa: tipik JWT'ler imzalanır, şifrelenmez
• Uzun ömürlü tokenlar gerekiyorsa: yüksek değerli oldukları için çalınmaya değebilir

Basit oturum cookie'lerinin daha iyi olduğu durumlar

Geleneksel sunucu tarafı render edilen web uygulamaları için, hızlı geçersiz kılma gerekiyorsa sunucu tarafı oturumlar ve HttpOnly cookie'ler genelde daha basit ve daha güvenlidir.

Hızlı karar kontrol listesi

JWT seçin eğer doğrulamanın servislere dağıtılmış halde durumsuz yapılması gerekiyorsa ve tokenları kısa ömürlü tutabiliyorsanız.

JWT'den kaçının eğer anında iptal gerekiyorsa, token içine hassas veri koyacaksanız veya oturum cookie'leri sorunsuz uygulanabiliyorsa.

Pratik kontrol listesi ve SSS

Doğrulama kontrol listesi (her seferinde ne kontrol edilmeli)

1. İmza geçerli mi

Doğru anahtar ve beklenen algoritma ile doğrulayın. Geçersiz imzaları reddedin—istisna yok.

2. exp (süresi dolma)

Tokenin süresi dolmamış olmalı.

3. nbf (kullanılmadan önce)

Varsa tokenin erken kullanılmadığından emin olun.

4. aud (audience)

Tokenin sizin API/service için olup olmadığını doğrulayın.

5. iss (issuer)

Tokenin beklenen issuer tarafından verildiğini doğrulayın.

6. Sağduyu kontrolleri (önerilen)

Token formatını doğrulayın, maksimum boyut uygulayın ve beklenmeyen claim türlerini reddederek kenar durum hatalarını azaltın.

HS256 vs RS256/ES256 seçimi

• HS256 (simetrik anahtar): tek bir gizli anahtar hem imzalar hem doğrular.

  • İyi: tek bir app/API tarafından kontrol edilen durumlar.
  • Dikkat: doğrulayıcı anahtara sahip olan herkes token da oluşturabilir.

• RS256 / ES256 (asimetrik anahtarlar): özel anahtar imzalar; genel anahtar doğrular.

  • İyi: birden çok servisin tokeni doğrulaması gerektiğinde; genel anahtarı dağıtmak imzalama yetkisi vermez.
  • Operasyonel not: sadece imzalayanın özel anahtara sahip olması nedeniyle rotasyon genellikle daha güvenlidir.

Genel kural: birden fazla bağımsız sistem tokenleri doğrulayacaksa (veya her doğrulayıcıya güvenmiyorsanız), RS256/ES256 tercih edin.

İzleme ve loglama (tokenleri sızdırmadan)

• Ham tokenleri loglamayın (headerlar, cookie'ler, query stringler).
• Eğer korelasyon gerekiyorsa, bir token parmak izi (ör. hash) veya güvenli meta veriler (iss, aud, ve politika izin veriyorsa bir kullanıcı ID'si) loglayın.
• Anormalliklere dikkat edin: imza hataları, süresi dolmuş token patlamaları, alışılmadık audience/issuer değerleri ve şüpheli yenileme desenleri.

SSS

JWT şifreli mi?

Varsayılan olarak hayır. Çoğu JWT imzalıdır, şifreli değildir. İçerik tokeni edinen herkes tarafından okunabilir. Gizlilik gerekiyorsa JWE kullanın veya hassas verileri JWT'de tutmayın.

Bir JWT'yi iptal edebilir miyim?

Sadece kendi başına duran access tokenlar kullanıyorsanız zor. Yaygın yaklaşımlar kısa ömürlü access tokenlar, yüksek riskli olaylar için kara listeler veya dönen refresh tokenlar kullanmaktır.

exp ne kadar olmalı?

UX ve mimarinizin izin verdiği kadar kısa. Birçok API erişim tokenlarını dakikalar düzeyinde tutar ve daha uzun oturumlar için refresh token kullanır.

Koder.ai ile JWT korumalı uygulamaları daha hızlı kurmak

JWT kimlik doğrulamasını yeni bir API veya SPA'da uyguluyorsanız, işin birçok kısmı tekrarlayıcıdır: middleware bağlamak, iss/aud/exp doğrulamaları, cookie bayraklarını ayarlamak ve token işleme sırasında loglara düşmemesini sağlamak.

Koder.ai ile bir web uygulaması (React), backend servisleri (Go + PostgreSQL) veya Flutter mobil uygulaması sohbet tabanlı bir akışla hızla oluşturabilir, güvenlik ayarlarını planlama modunda iyileştirip snapshot/rollback ile deneyebilir ve hazır olduğunuzda kaynak kodu dışa aktarabilirsiniz. Bu, JWT tabanlı kimlik doğrulama akışlarını hızlandırırken doğrulama mantığı, anahtar rotasyonu stratejisi ve dağıtım/host ayarları üzerinde kontrol sahibi olmanızı sağlar (custom domains dahil).