JSON Web Token (JWT), REST API'lerde istemci-sunucu arasında güvenli ve durumsuz kimlik doğrulama sağlayan endüstri standardı bir yöntemdir. JWT, kullanıcı bilgilerini şifreli bir şekilde token içinde taşıyarak her istekte veritabanı sorgusuna gerek kalmadan kimlik kontrolü yapmanızı sağlar. Bu yazıda, JWT tabanlı kimlik doğrulamayı API'nize entegre ederken dikkat etmeniz gereken pratik ipuçlarını ve kapsamlı bir kontrol listesini bulacaksınız.
JWT'nin Temel Bileşenleri ve Çalışma Prensibi
JWT üç bölümden oluşur: header, payload ve signature. Header, token tipini ve imzalama algoritmasını belirtir. Payload, kullanıcıya ait claim'leri (örneğin kullanıcı ID, rol, token süresi) taşır. Signature ise bu iki bölümün base64 kodlanmış halleri ile gizli anahtar kullanılarak oluşturulur. Sunucu, gelen token'ı aynı anahtarla doğrulayarak bütünlüğü kontrol eder.
JWT'yi kullanırken en kritik nokta, gizli anahtarın güvenliğidir. Anahtarınızı asla kod içinde düz metin olarak saklamayın; ortam değişkenleri veya güvenli bir anahtar yönetim servisi kullanın. Ayrıca, payload'da hassas bilgileri (şifre, kredi kartı) tutmayın, çünkü payload sadece base64 kodlanır, şifrelenmez.
Token Oluşturma ve Doğrulama Sürecinde Altın Kurallar
Token oluştururken exp (expiration) claim'ini mutlaka ekleyin. Kısa süreli access token (15-30 dakika) ve uzun süreli refresh token (7-30 gün) kullanarak güvenliği artırın. Refresh token'ı veritabanında saklayın ve gerektiğinde iptal edilebilir yapın.
- Algoritma seçimi: HS256 (simetrik) veya RS256 (asimetrik) kullanın. RS256, anahtar dağıtımı kolay olduğu için mikroservis mimarilerinde önerilir.
- Token süresi: Access token süresi 15 dakikayı geçmesin. Refresh token için 7 gün idealdir; daha uzun süreler risk oluşturur.
- İmzalama: Anahtarınızı düzenli aralıklarla değiştirin. Eski anahtarla imzalanmış token'ları geçersiz kılmak için anahtar rotasyonu uygulayın.
Token doğrularken signature'ı kontrol etmekle kalmayın; ayrıca iss (issuer) ve aud (audience) claim'lerini de doğrulayın. Bu, token'ın güvendiğiniz bir kaynak tarafından oluşturulduğunu ve doğru hedef API için geçerli olduğunu garanti eder.
Token Saklama ve İletim Güvenliği
Token'ı istemci tarafında saklarken XSS ve CSRF saldırılarına karşı önlem alın. En güvenli yöntem, token'ı httpOnly ve Secure flag'leri ile işaretlenmiş bir çerezde saklamaktır. Alternatif olarak, localStorage kullanıyorsanız CSRF koruması ekleyin.
| Saklama Yöntemi | Avantajlar | Riskler |
|---|---|---|
| httpOnly Çerez | XSS saldırılarına karşı dayanıklı, otomatik gönderim | CSRF koruması gerektirir, subdomain saldırılarına açık |
| localStorage | Basit kullanım, manuel gönderim kontrolü | XSS ile token çalınabilir |
| Memory (değişken) | En güvenli, kalıcı depolama yok | Sayfa yenilemede kaybolur |
Token iletiminde her zaman HTTPS kullanın. Token'ı Authorization header'ında Bearer formatında gönderin. URL parametrelerinde token göndermekten kaçının, çünkü loglara yazılabilir.
Token Yenileme (Refresh Token) Stratejisi
Refresh token ile access token süresi dolduğunda yeni token alınır. Refresh token'ı veritabanında saklayın ve kullanıcıya bağlayın. Her yenileme işleminde eski refresh token'ı iptal edip yeni bir tane oluşturun. Bu, token sızıntısı durumunda zararı sınırlar.
Refresh token rotasyonu yaparken reuse detection uygulayın: Eğer çalıntı bir refresh token kullanılırsa, hem eski hem de yeni token'ı iptal ederek kullanıcıyı tekrar giriş yapmaya zorlayın. Bu yaklaşım, saldırganın sürekli token almasını engeller.
Sık Yapılan Hatalar ve Kaçınılması Gerekenler
- Payload'a gereksiz veri eklemek: Token boyutunu büyütür ve bant genişliğini artırır. Sadece gerekli claim'leri koyun.
- Token'ı veritabanında doğrulamak: JWT'nin amacı durumsuzluktur; her istekte veritabanı sorgusu yaparsanız avantajını kaybedersiniz. Ancak kara liste (blacklist) gerekiyorsa Redis gibi hızlı bir önbellek kullanın.
- Zayıf gizli anahtar: Anahtarınız en az 256 bit uzunluğunda ve rastgele olsun. “secret” gibi basit anahtarlar kullanmayın.
- Token süresini çok uzun tutmak: Güvenlik riskini artırır. Kısa süreli access token kullanın.
JWT implementasyonunuzu düzenli olarak gözden geçirin. Merkezi hata yönetimi ile JWT doğrulama hatalarını (örneğin süresi dolmuş token, geçersiz imza) düzgün şekilde ele alın. Ayrıca, API versiyonlama stratejinizle uyumlu çalışması için token yapınızı planlayın. Detaylı bilgi için API versiyonlama rehberimize göz atabilirsiniz.
Kontrol Listesi: JWT Entegrasyon Adımları
- Güçlü bir gizli anahtar oluşturun ve ortam değişkeninde saklayın.
- Access token için 15 dakika, refresh token için 7 gün süre belirleyin.
- Token oluştururken exp, iss, aud claim'lerini ekleyin.
- İmzalama algoritması olarak HS256 veya RS256 kullanın.
- Token doğrularken signature ve claim'leri kontrol edin.
- Token'ı httpOnly+Secure çerezde saklayın; localStorage kullanıyorsanız CSRF önlemi alın.
- Refresh token rotasyonu ve reuse detection uygulayın.
- Token yenileme endpoint'ini rate limit ile koruyun.
- Hata durumlarında uygun HTTP durum kodları döndürün (401, 403).
- Düzenli güvenlik taramaları yapın ve anahtarları periyodik yenileyin.
JWT ile kimlik doğrulama, doğru yapılandırıldığında hem güvenli hem de performanslı bir çözüm sunar. Yukarıdaki ipuçlarını ve kontrol listesini uygulayarak API'nizi güvence altına alabilirsiniz. Daha fazla bilgi için REST API sayfalama stratejileri yazımızı da inceleyebilirsiniz.
Sık Sorulan Sorular
JWT ile access token ve refresh token arasındaki fark nedir?
Access token, kullanıcının API'ye erişimini sağlayan kısa süreli (genelde 15-30 dk) token'dır. Refresh token ise daha uzun süreli (7-30 gün) olup, access token süresi dolduğunda yeni bir access token almak için kullanılır. Refresh token veritabanında saklanarak iptal edilebilir.
JWT token'ı nerede saklamalıyım?
En güvenli yöntem, httpOnly ve Secure flag'leri ile işaretlenmiş bir çerezde saklamaktır. Bu, XSS saldırılarına karşı korur. localStorage kullanıyorsanız CSRF koruması eklemeniz gerekir. Token'ı asla URL parametresinde veya düz metin olarak loglarda saklamayın.
JWT imzalama algoritması olarak HS256 mı RS256 mı tercih edilmeli?
HS256 simetrik şifreleme kullanır, tek bir gizli anahtarla çalışır. RS256 asimetrik şifreleme kullanır ve özel/ortak anahtar çifti gerektirir. Mikroservis mimarilerinde RS256 önerilir çünkü ortak anahtarlar dağıtılabilir. Tek bir sunucu için HS256 yeterlidir.
JWT token süresi dolduğunda ne yapmalıyım?
Süresi dolan access token için refresh token kullanarak yeni bir access token alın. Refresh token da süresi dolmuşsa veya iptal edilmişse kullanıcıyı tekrar giriş yapmaya yönlendirin. Token yenileme sırasında refresh token rotasyonu uygulayarak güvenliği artırın.
