JWT Token Rotasyonunu Yenile: Gerçek Sistemler için Güvenli Model

JWT eğitimlerinin çoğu "uzun ömürlü oturumlar için yenileme belirteci kullanın" noktasında durur. Bu yenileme jetonu çalındığında ne olacağını nadiren açıklarlar. Hiçbir zaman değişmeyen statik yenileme belirteci, saldırgana çalınan bir oturum çereziyle aynı kalıcı erişimi sağlar. Daha da kötüsü hırsızlığı tespit etmenin bir yolu yok.

Jeton rotasyonunu yenile her kullanımda yeni bir yenileme jetonu yayınlayarak bu sorunu çözer. Eski bir jetonun tekrar oynatılması durumunda oturumun tamamı iptal edilir. Bu makalede Auth0, Okta ve diğer ciddi kimlik sağlayıcıları tarafından kullanılan uygulama modeli açıklanmaktadır.

Statik Yenileme Belirteçleri Neden Başarısız Oluyor

Statik yenileme jetonunun tüm oturum ömrü boyunca (genellikle 30+ gün) sabit bir değeri vardır. Sorunlar:

• Hırsızlık sessizdir — bir saldırgan yenileme jetonunu çalarsa, kullanıcının haberi olmadan süresiz olarak yeni erişim jetonları oluşturabilir
• Tekrar algılama yok — aynı jeton farklı konumlardan tekrar tekrar kullanılabilir
• İptal kabadır — çalınan bir jetonu geçersiz kılmak için genellikle tüm kullanıcı oturumlarını geçersiz kılmanız gerekir

Çözüm, her yenileme jetonunun tek kullanımlık olarak ele alınmasıdır.

Rotasyon Modeli

1. Adım: Giriş Yapın — Bir Token Ailesi Oluşturun

Kullanıcı kimlik doğrulaması yaptığında, bu oturumdaki tüm belirteçleri gruplandıran bir family_id (UUID) oluşturun:

{ family_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479", user_id: "user_123", refresh_token_hash: sha256(refresh_token), created_at: "2026-03-28T10:00:00Z", expires_at: "2026-04-27T10:00:00Z", used: false
}

Bu kaydı sunucu tarafında saklayın. Yenileme belirteçlerini asla localStorage'da saklamayın; httpOnly çerezleri kullanın veya yerel depolamayı güvenli hale getirin.

2. Adım: Jeton Yenileme — Döndürme

İstemci yenileme jetonunu sunduğunda:

1. Veritabanındaki jeton karmasını arayın
2. Aktif bir aileye ait olduğunu ve used
olarak işaretlenmediğini doğrulayın
3. used olarak işaretle: true
4. Bir new yenileme jetonu verin (yeni rastgele değer, aynı family_id)
5. Yeni bir erişim belirteci yayınlayın
6. Yeni yenileme belirteci karmasını depolayın

3. Adım: Tekrar Oynatma Algılaması

used: true olarak işaretlenmiş bir yenileme jetonu tekrar sunulursa, bu şu anlama gelir:

• Saldırgan çalınan bir jetonu tekrar oynatıyor veya
• Meşru bir istemci, bir ağ hatasından sonra yeniden deniyor

Güvenli yanıt: ailedeki tüm belirteçleri iptal edin. Bu, kullanıcıyı tekrar oturum açmaya zorlar. Bir saldırganın erişimi sürdürmesine izin vermek yerine meşru bir kullanıcıyı bir kez rahatsız etmek daha iyidir.

// Tekrar oynatma algılandı — nükleer seçenek
db.query'yi bekliyoruz( 'Refresh_tokens'DAN SİL WHERE family_id = $1', [aile kimliği]
);

Veritabanı Şeması

Minimum yenileme belirteci tablosu:

TABLO OLUŞTUR yenileme_belirteçleri ( id UUID BİRİNCİL ANAHTAR VARSAYILAN gen_random_uuid(), family_id UUID BOŞ DEĞİL, user_id UUID BOŞ REFERANS DEĞİL kullanıcılar(id), token_hash METİN BOŞ EŞSİZ DEĞİL, BOOLE VARSAYILAN YANLIŞ kullanılmış, created_at TIMESTAMPTZ DEFAULT now(), TIMESTAMPTZ NOT NULL tarihinde sona eriyor, UUID REFERANSLARI ile değiştirildi_yenileme_tokens(id)
); CREATE INDEX idx_refresh_family ON yenileme_tokens(family_id);
CREATE INDEX idx_refresh_user ON yenileme_tokens(user_id);

replaced_by sütunu, denetim amacıyla takip edebileceğiniz bir zincir oluşturur.

Eşzamanlı İstekleri İşleme

Gerçek uygulamalarda, birden fazla API çağrısı aynı anda yenilemeyi tetikleyebilir. Çağrı B hala eski jetonu tutarken Çağrı A jetonu döndürürse, Çağrı B tekrar algılamayı tetikleyerek kullanıcının beklenmedik bir şekilde oturumunu kapatır.

Etkisiz Dönem Modeli

Önceki yenileme belirtecinin döndürme sonrasında kısa bir süre (5-10 saniye) geçerli kalmasına izin ver:

const GRACE_PERIOD_MS = 10_000; if (belirteç.kullanılmış) { const geçen = Date.now() - token.rotated_at; if (geçti < GRACE_PERIOD_MS) { // Within grace period — return the already-issued new tokens return getLatestTokensForFamily(token.family_id); } // Outside grace period — replay attack await revokeFamily(token.family_id); throw new UnauthorizedError('token_replayed');
}

İzleme ve Uyarılar

Üretimde şu sinyalleri izleyin:

• Saat başına etkinlikleri tekrar oynat — ani artış, etkin bir saldırıyı veya istemci tarafında bir hatayı gösterir
• Aile iptalleri — yüksek oranlar, jeton hırsızlığına veya yanlış yapılandırılmış bir istemciye işaret edebilir
• Kullanıcı başına yenileme hızı — anormal derecede yüksek oranlar, token hasadının yapıldığını gösteriyor
• Coğrafi anormallikler — orijinal giriş bilgilerinin bulunduğu ülkeden farklı bir ülkeden yenileme

Yenileme Jetonu ve Erişim Jetonu: Hızlı Referans

Genellikle yenileme akışlarıyla etkileşime giren zaman talebi doğrulama hataları için bkz. JWT exp/iat/nbf yaygın hatalar.

İlgili Araçlar ve Makaleler

• JWT Kod Çözücü — belirteçleri inceleyin ve zaman taleplerini doğrulayın
• JWT Güvenlik Hataları — yenileme belirteçlerinin ötesinde yaygın JWT tuzakları
• JWT Zaman Talebi Hataları — saat çarpıklığı ve doğrulama sırası sorunları
• 2FA Kılavuzu — kimlik doğrulamayı belirteçlerin ötesinde güçlendirin