JSON Web Token (JWT) Nedir ve Nasıl Çalışır? Rehber

• JWT Tanımı: JSON Web Token (RFC 7519), taraflar arasında güvenli ve kendinden kapsamlı (self-contained) bilgi aktarımı sağlayan kompakt bir standarttır.
• Anatomik Yapı: Bir JWT; Header, Payload ve Signature olmak üzere nokta (.) ile ayrılmış üç ana bölümden oluşur.
• İmza Güvenliği: HMAC-SHA256 veya RSA algoritmalarıyla imzalanan jetonlar, verinin yolda tahrif edilmesini önler.
• Kullanım Alanları: Stateless kimlik doğrulama (auth), OAuth2 erişim jetonları ve mikroservisler arası yetkilendirme standartlarında tercih edilir.

Modern web uygulamalarında, mobil istemcilerde ve mikroservis mimarilerinde oturum yönetimi ve kimlik doğrulama süreçleri JWT (JSON Web Token) standardı üzerine kurgulanır. İstemci ile sunucu arasında durum bilgisi tutmayan (stateless) bir iletişim modeli sunan JWT, sunucu tarafında veritabanı oturum yükünü tamamen ortadan kaldırır.

Geliştirme aşamasında jeton içeriklerini çözümlemek için JWT Dekoder aracımızı kullanabilirsiniz. Jeton imzalarında kullanılan kriptografik mantığı kavramak için HMAC nedir makalemizi inceleyebilirsiniz.

JWT Nedir ve Nasıl Çalışır?

JSON Web Token (RFC 7519), JSON formatındaki hak taleplerini (claims) dijital olarak imzalanmış şekilde taşımak üzere tasarlanmış açık bir endüstri standardıdır. Sunucu kullanıcıyı başarılı bir şekilde doğruladığında (login), kullanıcı bilgilerini barındıran bir JWT üretir ve bunu istemciye teslim eder.

İstemci sonraki isteklerde bu jetonu HTTP Authorization başlığında Bearer <token> formatında sunucuya gönderir:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sunucu gelen jetonun imzasını gizli anahtarı (secret key) ile doğrular. İmza geçerliyse veri tabanına oturum sorgusu atmadan isteği onaylar.

JWT'nin Üç Ana Parçası ve Anatomisi

Bir JWT karakter dizisi noktalarla ayrılmış üç farklı bölümden oluşur: Header.Payload.Signature. Her bölüm Base64URL algoritması ile kodlanır. Karakter kodlamasının temelleri için Base64 kodlama rehberimize göz atabilirsiniz.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFobWV0IiwiYXR0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header (Başlık)

Header bölümü jetonun tipini (JWT) ve imzalama algoritmasını (HS256, RS256 gibi) tanımlar:

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

2. Payload (Gövde / Hak Talepleri)

Payload bölümü kullanıcı id'si, rolü ve jetonun geçerlilik süresi gibi hak taleplerini (claims) içerir. Üç tür claim tanımlıdır:

• Registered (Kayıtlı): iss (yayınlayan), exp (son kullanma tarihi), sub (konu), aud (hedef kitle) gibi standart alanlar.
• Public (Genel): Çakışmaları önlemek için IANA kayıtlarında tanımlanan alanlar.
• Private (Özel): Uygulamaya özgü kullanıcı id veya rol verileri.

{
  "sub": "usr-1001",
  "name": "Ahmet Yilmaz",
  "role": "admin",
  "exp": 1775000000
}

3. Signature (İmza)

İmza bölümü Header ve Payload bölümlerinin gizli anahtar ile şifrelenmesiyle elde edilir. Sunucu tarafında verinin değiştirilmediğini doğrular:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret_key
)

Simetrik ve Asimetrik İmzalama Algoritmaları

JWT imzalanırken iki farklı kriptografik yaklaşım tercih edilebilir:

1. Simetrik Algoritmalar (HS256 - HMAC-SHA256): İmzayı üreten ve doğrulayan taraf aynı gizli anahtarı (secret key) paylaşır. Tek bir backend servisi ve veritabanı içeren uygulamalarda hızlı ve pratiktir.
2. Asimetrik Algoritmalar (RS256 - RSA / ES256 - ECDSA): Özel anahtar (private key) jetonu imzalar, açık anahtar (public key) ise imzayı doğrular. Kimlik doğrulama sunucusunun (Auth Server) jeton ürettiği, mikroservislerin ise yalnızca doğrulama yaptığı dağıtık mimarilerde en güvenli yaklaşımdır.

OAuth 2.0 ve OpenID Connect (OIDC) Entegrasyonu

Modern mimarilerde JWT, OAuth 2.0 yetkilendirme protokolünün ve OpenID Connect (OIDC) kimlik doğrulama katmanının temel yapı taşıdır. OIDC spesifikasyonu kullanıcı kimliğini temsil etmek için ID Token olarak JWT formatını kullanır.

Erişim jetonları (Access Token) mikroservisler arasında taşınırken API Gateway tarafından hızlıca doğrulanır. Bu sayede her mikroservis kendi içinde merkezi bir Auth servisine bağımlı kalmadan kullanıcı yetkilerini kontrol edebilir.

Dağıtık mimarilerde JWKS (JSON Web Key Set) uç noktaları kullanılarak açık anahtarlar periyodik olarak önbelleğe alınır. Bu sayede her doğrulama isteğinde anahtar sunucusuna yük bindirilmez. Ağ bant genişliğini verimli kullanmak için imzalama algoritmaları optimizasyonu yapılır. Kurumsal düzeydeki kimlik doğrulama servislerinde jeton üretimi ve doğrulaması milisaniyeler seviyesinde gerçekleşir.

İstemci Tarafında Saklama ve Güvenlik Best Practice'leri

JWT'lerin tarayıcıda saklanma yöntemi güvenlik zafiyetlerinin önüne geçmek için kritik önem taşır.

• LocalStorage / SessionStorage: XSS (Cross-Site Scripting) zafiyetlerine karşı korumasızdır. Saldırgan zararlı bir script ile localStorage.getItem() çağırarak jetonu ele geçirebilir.
• HttpOnly ve SameSite Çerezleri (Recommended): JWT'nin HttpOnly, Secure ve SameSite=Strict bayraklarıyla çerezde saklanması, JavaScript erişimini engelleyerek XSS saldırılarına karşı en üst düzey korumayı sağlar.

Diğer kritik güvenlik önlemleri:

• Alg: None Saldırısı: Sunucu tarafında alg: none içeren jetonların kesinlikle reddedilmesi gerekir.
• Güçlü Secret Key: HMAC imzalarında tahmin edilemeyen en az 256-bit gizli anahtarlar seçilmelidir.
• Kısa Ömürlü Jetonlar (exp): Access Token ömrü kısa tutulmalı (15 dakika), yenileme işlemleri Refresh Token ile yürütülmelidir.

Sistem güvenliğini artırmak amacıyla jeton rotasyonu (token rotation) uygulanarak çalınan jetonların kullanım ömrü kısıtlanır. Bu güvenlik mekanizmaları modern web sistemlerini siber tehditlere karşı dirençli tutar ve veri gizliliğini en üst seviyede sağlar. Yazılım ekipleri güvenlik mimarilerini sürekli denetlemeli, güncellemeli ve proaktif güvenlik önlemleri almalıdır. Sistem güncellemeleri düzenli yapılmalıdır.

Sıkça Sorulan Sorular

JWT verisi şifrelenmiş midir, herkes içeriğini görebilir mi?

Standart JWT şifrelenmemiş, sadece imzalanmıştır. Herkes Base64 kodunu çözerek içeriği görebilir; ancak gizli anahtar olmadan içeriği değiştiremez.

JWT iptali (Token Revocation) nasıl sağlanır?

JWT durum bilgisi tutmadığı için tek taraflı iptali zordur. İptal mekanizması için jeton kimlikleri (jti) kara listeye (blacklist) alınabilir veya veritabanında saklanan Refresh Token geçerliliği kaldırılabilir.

Access Token ve Refresh Token arasındaki fark nedir?

Access Token kısa ömürlüdür (örneğin 15 dakika) ve API isteklerini doğrulamak için kullanılır. Refresh Token ise uzun ömürlüdür ve yeni Access Token almak için güvenli ortamda kullanılır.