Kimlik katmanında en pahalı incident’lardan biri şudur: “Login çalışıyor ama tüm servisler 401 dönüyor.” Sebep çoğu zaman uygulama kodu değil, anahtar rotasyonudur: JWT imzalama anahtarı değişir, JWKS güncellenir; ama istemciler/gateway’ler eski JWKS’yi cache’te tutmaya devam eder.
Bu runbook; “kid mismatch” sınıfı hatayı hızlı teşhis etmek ve rotasyonu kurumsal ölçekte güvenli hâle getirmek için hazırlanmıştır.
1) Semptomlar: ne zaman JWKS şüphesi doğar?
Tipik sinyaller:
- 401/403 oranı ani yükselir
- Sorun tüm servislerde aynı anda görünür (gateway/edge doğrulama yapıyorsa)
- Deploy ile aynı dakikalarda başlar (IdP/gateway değişikliği)
- Log’larda “unknown kid”, “no matching key”, “signature verification failed”
2) Triage: 10 dakikada kanıt üret
2.1 Hangi kid patlıyor?
Örnek log araması (uyarlayın):
rg -n "kid|jwks|signature|unknown key|no matching" /var/log -S | headAmaç: hata mesajındaki kid değerini yakalamak.
2.2 JWKS endpoint’i gerçekten yeni anahtarı yayımlıyor mu?
Operasyon tarafında en iyi test, sadece “endpoint açılıyor mu?” değil, kid listesidir.
curl -fsS https://<idp-or-gateway>/.well-known/jwks.json | jq -r '.keys[].kid'Eğer kid listesinde hata alan token’ın kid’i yoksa:
- Rotasyon “tek anahtar” olarak yapılmış olabilir (overlap yok)
- Yanlış environment deploy olmuş olabilir
- CDN/LB katmanı eski JWKS yanıtını taşıyor olabilir
2.3 Cache katmanını tespit et (en kritik adım)
JWKS çoğu zaman şu katmanlarda cache’lenir:
- API gateway / reverse proxy (Envoy, NGINX, Kong vb.)
- Uygulama içinde JWKS cache (SDK)
- CDN (yanlış Cache-Control ile)
3) Hızlı mitigasyon: 401 dalgasını durdur
Öncelik: üretimi geri getir. Sonra rotasyonu “doğru” yap.
3.1 Eski anahtarı geri yayımla (en hızlı geri dönüş)
Eğer mümkünse JWKS’de eski + yeni anahtarı birlikte yayımla (overlap). Böylece:
- Cache’ler yeni JWKS’yi aldığında bile eski token’lar doğrulanır
- Aşamalı geçiş yapabilirsin
3.2 JWKS cache süresini geçici düşür
Geçici politika:
Cache-Control: max-age=60(veya daha düşük)- Gateway’lerde JWKS refresh periyodunu kısalt
- CDN’de JWKS path’ini bypass/purge et
3.3 “kid” üretim stratejisini düzelt
Hatalı pratik: aynı kid ile farklı anahtar yayımlamak. Bu, cache ile birleşince doğrulama kaosuna döner.
Doğru pratik:
kiddeğişince anahtar değişmiş demektir.- Eski
kidbir süre daha JWKS’de kalır (grace period).
4) Kalıcı çözüm: güvenli rotasyon tasarımı
4.1 Overlap (çift anahtar) penceresi tanımla
Operasyonel kural önerisi:
- “Eski anahtar JWKS’de en az 2× maksimum token TTL kadar kalır.”
Örnek:
- Token TTL: 30 dk
- Overlap: ≥ 60 dk
4.2 Rotasyon checklist (deploy öncesi)
- Yeni anahtar üretildi, yeni
kidhazır - JWKS’de eski+yeninin birlikte yayınlandığı doğrulandı
- JWKS Cache-Control bilinçli belirlendi
- Gateway/JWKS cache refresh aralığı biliniyor
- 401 oranı için alarm ve dashboard hazır
4.3 Alarm ve doğrulama
Önerilen metrikler:
- 401 oranı (gateway + servis bazlı)
- “unknown kid” log oranı
- JWKS fetch hata oranı / latency
5) Runbook kapanış: rotasyon sonrası temizlik
Rotasyon stabil olduktan sonra:
- Eski anahtarı kaldırmadan önce token TTL’in dolduğunu doğrula
- Cache ayarlarını normal seviyeye çek (çok sık fetch de gereksiz yük)
- Postmortem’e “hangi cache katmanı uzattı?” sorusunu ekle
Anahtar rotasyonu, sadece güvenlik işi değil; operasyonel süreklilik işidir. Güvenli kurumlar, rotasyonu “bir kere yapıp unutulan” görev değil, tekrar eden ve tatbikatı yapılan bir değişiklik olarak yönetir.