JWT access token ve refresh token sistemi nasıl kurulur?

Kısa ömürlü JWT access token, döndürülen refresh token, yeniden kullanım tespiti ve güvenli çerez ayarlarıyla sağlam bir oturum yenileme sistemi kurun.

JWT access token ve refresh token sistemi, API isteklerini kısa ömürlü bir erişim belirteciyle yetkilendirirken kullanıcıyı her süre dolduğunda yeniden giriş yapmaya zorlamamak için kullanılır. Güvenli tasarımın temelinde kısa access token süresi, sunucuda izlenebilen refresh token oturumu ve her yenilemede token rotation bulunur.

JWT kullanmak tek başına sistemi güvenli yapmaz. Token’ın nerede saklandığı, çalınan refresh token’ın yeniden kullanılıp kullanılmadığının nasıl anlaşılacağı ve logout sırasında hangi kaydın iptal edildiği tasarımın asıl parçalarıdır.

Access token ve refresh token görevlerini ayırın

Access token API’ye gönderilir ve kullanıcı kimliği, hedef kitle, issuer, yetkiler ile kısa bir sona erme süresi taşır. API her istekte imzayı, iss, aud, exp ve gerekiyorsa nbf alanlarını doğrulamalıdır. Sadece token’ın decode edilebilmesi geçerli olduğu anlamına gelmez.

Refresh token yalnızca yenileme endpoint’ine gönderilir. Uzun ömürlü olduğu için veritabanında oturum kaydıyla ilişkilendirilmesi, hash’lenerek saklanması ve iptal edilebilmesi daha güvenli bir modeldir. Refresh token’ın JWT olması zorunlu değildir; yüksek entropili rastgele bir değer daha kolay yönetilebilir.

Önerilen oturum tablosu

CREATE TABLE refresh_sessions (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  token_hash CHAR(64) NOT NULL UNIQUE,
  family_id UUID NOT NULL,
  expires_at TIMESTAMP NOT NULL,
  used_at TIMESTAMP NULL,
  revoked_at TIMESTAMP NULL,
  replaced_by UUID NULL,
  created_at TIMESTAMP NOT NULL
);

Veritabanı ele geçirilirse düz refresh token’ların doğrudan kullanılmaması için token hash’i tutulur. Token değeri yalnızca oluşturulduğu anda istemciye verilir. Hash için hızlı ama kriptografik SHA-256, token yeterince rastgele ve uzun olduğunda karşılaştırma amacıyla kullanılabilir.

Yenileme akışında rotation uygulayın

İstemci refresh token’ı yalnızca HTTPS üzerinden yenileme endpoint’ine gönderir.
Sunucu token hash’ini bulur; süresini, iptal ve kullanım durumunu kontrol eder.
Geçerliyse eski kaydı kullanılmış olarak işaretler.
Yeni access token ile yeni refresh token üretir ve aynı family içinde yeni kayıt açar.
Eski token tekrar gelirse olası token hırsızlığı kabul edilerek ilgili family iptal edilir.

Bu işlemler yarış durumunu önlemek için tek veritabanı transaction’ında yapılmalıdır. Mobil uygulama veya zayıf bağlantı nedeniyle aynı yenileme isteğinin istemeden iki kez gönderilebileceğini hesaba katan, kısa ve kontrollü bir tekrar politikası tasarlanabilir; fakat eski token sınırsız yeniden kullanılamamalıdır.

Tarayıcıda saklama tercihi

Refresh token için HttpOnly, Secure ve uygun SameSite ayarına sahip cookie, JavaScript’in token’a doğrudan erişmesini engeller. Cookie kullanıldığında CSRF modeli ayrıca ele alınmalıdır. SameSite ayarı mimariye uymuyorsa CSRF token veya origin kontrolü gibi ek koruma gerekir.

Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Lax; Path=/auth/refresh

Access token’ı localStorage’da uzun süre tutmak XSS durumunda token’ın okunmasına yol açabilir. Uygulama mimarisine göre bellekte kısa süreli saklama veya Backend for Frontend yaklaşımı değerlendirilebilir.

İmzalama ve anahtar yönetimi

Algoritmayı sunucu config’inde sabitleyin; token header’ının istediği algoritmayı körlemesine kabul etmeyin. Dağıtık sistemlerde asimetrik anahtarlar ve kid ile kontrollü anahtar rotasyonu kullanılabilir. Gizli anahtarları kaynak kodda veya istemci uygulamasında tutmayın.

Logout ve güvenlik olayları

Logout sırasında refresh oturumunu sunucuda iptal edin ve cookie’yi aynı path/domain ayarlarıyla silin. Parola değişikliği, hesap kapatma, şüpheli cihaz veya refresh token yeniden kullanımında ilgili oturumları ya da tüm kullanıcı oturumlarını iptal edebilmelisiniz. Kullanılmayan refresh oturumlarına hareketsizlik süresi uygulayın.

Token değerlerini log’a yazmayın. Loglarda oturum ID’si, kullanıcı ID’si, olay türü ve zaman bilgisi yeterlidir; kişisel ve güvenlik açısından hassas verileri en aza indirin.