Token Yönetim Ayarları
Yönetim → Sistem Ayarları → Token Yönetim Ayarları yolunu izleyerek bu ekrana erişebilirsiniz. Buradaki ayarlar yalnızca token uç noktasının ürettiği yanıt gövdesini etkiler; varsayılan değerler mevcut çalışma şeklini bozmaz.
Token Yanıt Alan İsimleri
Token uç noktasının döndürdüğü JSON yanıt gövdesindeki standart alan isimlerini değiştirebilir veya bir alanı tamamen yanıttan çıkarabilirsiniz. Varsayılan isimler OAuth2 RFC 6749 standardındadır.
| Alan | Açıklama |
|---|---|
| access_token alan adı | Erişim token'ının döndüğü alanın adıdır. Bu alan RFC 6749 §5.1 gereği zorunludur; yeniden adlandırılabilir ancak yanıttan çıkarılamaz. |
| token_type alan adı | Token türünün döndüğü alanın adıdır. "Response'a dahil et" kapatılırsa yanıtta yer almaz. |
| expires_in alan adı | Token geçerlilik süresinin döndüğü alanın adıdır. "Response'a dahil et" kapatılırsa yanıtta yer almaz. |
| refresh_token alan adı | Yenileme token'ının döndüğü alanın adıdır. "Response'a dahil et" kapatılırsa yanıtta yer almaz. |
| scope alan adı | Token ile birlikte dönen scope (kapsam) alanının adıdır. "Scope alanını response'a dahil et" kapatılırsa scope yanıta hiç eklenmez. |
Bu ayarlar yalnızca token yanıt gövdesini etkiler. JWT token'ın içine gömülen scope bilgisinin adı değiştirilmez; bu sayede token'ı doğrulayan alıcı sistemler etkilenmez.
expires_in Değer Birimi
Token uç noktası varsayılan olarak expires_in alanını milisaniye cinsinden döner (eski Apinizer davranışı). RFC 6749 §5.1, expires_in değerini token ömrü olarak saniye cinsinden tanımlar; bu nedenle katı (strict) bir OAuth2 istemcisi milisaniye değerini yanlış yorumlayabilir (örneğin 60000 değerini 60 saniye yerine ~16,6 saat sanıp) token'ı zamanında yenilemeyebilir.
| Seçenek | Davranış |
|---|---|
| expires_in Değerini Saniye Olarak Dön (Varsayılan olarak devre dışı) | Devre dışı bırakıldığında expires_in milisaniye cinsinden döner (geriye dönük uyumluluk için korunan eski davranış). Etkinleştirildiğinde RFC 6749 §5.1 gereği saniye cinsinden döner. |
Bu seçenek yalnızca yanıttaki expires_in alanını etkiler. JWT exp claim'i (mutlak zaman damgası) ile X-IssuedAt / X-ExpiresAt yanıt alanları etkilenmez.
Mevcut istemcileriniz halihazırda milisaniye değerine göre düzeltme yapıyorsa, bu seçeneği etkinleştirmek hesapladıkları ömrü yarıya indirir ve erken token yenilemelerine yol açabilir. Mevcut entegrasyonlar için devre dışı bırakın; RFC uyumlu saniye bekleyen yeni entegrasyonlar için etkinleştirin.
Bir API istemcisiyle alınan token'da expires_in bu ayardan bağımsız olarak her zaman saniye cinsindendir. Bu istisna yalnızca API istemcilerini etkiler; kimlik bilgileriyle alınan token'lar yukarıdaki ayara aynen tabidir.
Scope Doğrulama Davranışı
Scope (kapsam), bir token isteğiyle hangi yetkilerin talep edildiğini belirten değerdir ve scope ile token alma akışında kullanılır. Çözümlenen scope, token ile birlikte yanıt gövdesinde geri döner. Bu davranış hem "Bu Poliçe'den Yönet" hem de "ACL'den Yönet" yönetim modunda aynı şekilde çalışır.
Yanıtta hangi scope'ların döneceği aşağıdaki iki ayara bağlıdır.
Scope Uyumsuzluğunda Davranış
İstemcinin talep ettiği scope'lardan bazıları, kullanıcı veya kimlik bilgisi üzerinde tanımlı değilse gateway'in nasıl davranacağını belirler.
| Seçenek | Davranış |
|---|---|
| Katı — Hata Dön (Varsayılan) | Talep edilen scope'lardan herhangi biri tanımlı değilse HTTP 400 invalid_scope hatası döner ve token verilmez. RFC 6749 §5.2 ile uyumludur. |
| Esnek — Ortak Scope ile Token Ver | Yalnızca tanımlı olan scope'larla token verilir; geçersiz scope'lar sessizce atılır. |
| İsteği Yoksay — Tüm Scope'lar | Talep edilen scope listesi yoksayılır; token, kullanıcı veya kimlik bilgisi üzerinde tanımlı tüm scope'larla verilir. |
İstekte Scope Yoksa Davranış
İstemci hiç scope talep etmediğinde token'ın scope alanının nasıl üretileceğini belirler.
| Seçenek | Davranış |
|---|---|
| Scope'suz Token (Varsayılan) | İstek scope içermiyorsa token scope'suz üretilir ve yanıta scope alanı eklenmez. |
| Tüm Scope'larla Doldur | İstek scope içermiyorsa tanımlı tüm scope'lar kullanılır ve yanıta eklenir. |
Principal'ın Rolü Yoksa Davranış
Varsayılan olarak, scope talep edildiğinde ancak kimliği doğrulanan kullanıcı veya kimlik bilgisinin hiç rolü yoksa, ağ geçidi açık başarısız davranır: boş scope'lu token çıkarır hata döndürmek yerine. Principal'ın Rolü Yoksa Reddet seçeneğini etkinleştirerek bu durumu, HTTP 400 invalid_scope hatası döndüren bir katı hataya dönüştürebilirsiniz; bu, daha sıkı tanılama için kullanışlıdır.
| Seçenek | Davranış |
|---|---|
| Principal'ın Rolü Yoksa Reddet (Varsayılan olarak devre dışı) | Etkinleştirildiğinde ve scope talep edilirken principal'ın rolü yoksa HTTP 400 invalid_scope hatası döndürülür. Devre dışı bırakıldığında boş scope'lu token çıkarılır (eski açık başarısız davranışı). |
Bu ayar İsteği Yoksay — Tüm Scope'lar uyumsuzluk modunda etkisiz olur, çünkü bu mod talep edilen scope'u tamamen yoksayar.
Scope'un dolu dönebilmesi için ilgili kullanıcıya veya kimlik bilgisine rol (scope) tanımlı olması gerekir. Rol tanımlama adımları için Scope ile Token Alma sayfasına bakabilirsiniz. Rol tanımlı değilse, Principal'ın Rolü Yoksa Reddet etkinleştirilmedikçe scope boş döner; etkinleştirildiğinde HTTP 400 invalid_scope hatası döndürülür.
Bir API istemcisinin bu sürümde kendine ait bir rolü/scope'u yoktur — yukarıdaki "rol tanımlı değilse" durumu bir API istemcisi için her zaman geçerlidir. Dolayısıyla Principal'ın Rolü Yoksa Reddet kapalıyken (varsayılan) bir API istemcisi her zaman scope'suz token alır; açıkken ve istek scope talep ediyorsa her zaman HTTP 400 invalid_scope ile reddedilir.
Token İptali Katılık Ayarı
İptal edilen token'lar her zaman iptal anında ölür: bir API istemcisi iptal edildiğinde açık (opaque) token'lar depodan silinir ve istemciye bir kesim noktası (cutoff) damgalanır — bu andan önce üretilmiş her JWT, süresi henüz dolmamış olsa bile, gateway'in doğrulamasında bu damgaya bakılarak reddedilir. İptal Katılığı ayarı bu akışı etkilemez; yalnızca kesim noktasının senkron olarak ulaşamadığı iki dar yoldaki kalıntı bayatlık penceresini kontrol eder — ikisi de yalnızca Bu Poliçe'den Yönet modunda çalışan JWT politikalarında ortaya çıkar:
- Kimlik/Yetki Doğrulama Servisi olarak Secret Manager dışında bir kaynak (LDAP, Veritabanı, API veya OIDC) seçili bir JWT politikasının ürettiği token'lar — bu politikada hiçbir kimlik bilgisi (credential) çözülmediği için kesim noktasının okuyacağı bir istemci de yoktur.
- Kimlik kaynağı Secret Manager olsa bile, client_credentials ile gelen ve issuer'ı hiçbir kimlik bilgisi kaydıyla eşleşmeyen eski tip makine-makine (M2M) token'ları — bunlarda da çözülen bir kimlik bilgisi, dolayısıyla kesim noktası yoktur.
| Seçenek | Davranış |
|---|---|
| Degraded — Yalnızca Cutoff (Varsayılan) | Yukarıdaki iki yolda üretilmiş bir JWT, iptalden sonra da kendi süresi dolana kadar geçerli kalmaya devam edebilir. Doğrulama hiçbir cache'e bakmaz; ek maliyet yoktur. |
| Strict — Cutoff + Denylist | Yukarıdaki iki yolda da her doğrulama, iptal edilmiş token'ların tutulduğu bir denylist cache'ine bakar; listede bulunan bir JWT süresi dolmamış olsa bile reddedilir. |
Strict mod, yalnızca bu iki yoldaki doğrulamalara bir cache okuması ekler. Cache'e o an erişilemiyorsa (bağlantı kopukluğu, zaman aşımı) doğrulama güvenli tarafta kalınarak reddedilir (fail-closed) — belirsizlik hiçbir zaman erişime açılmaz.
Strict modun kullandığı iptal-edilmiş-token listesi, bellek baskısı nedeniyle daraltılmaz: bir kayıt listeden yalnızca kendi kapsadığı token'ın süresi zaten dolduğunda düşer. Kurulum genelindeki genel cache kapasite ayarı bu listeye kasıtlı olarak uygulanmaz — aksi halde bellekle ilgili sıradan bir ayarlama, fark edilmeden bu güvenlik denetimini de daraltabilirdi. Bellek kısıtlı bir kurulum dilerse bu listeye özel, adı açıkça belirtilmiş bir kapasite ayarı (hazelcast.map.max.size.token-denylist) tanımlayabilir; ancak bu sınır konduğunda kapasite dolduğunda en az kullanılan kayıtlar silinir ve kapsadıkları iptal edilmiş token'lar kendi süreleri dolmadan önce yeniden geçerli hale gelebilir. Bu, yalnızca açıkça istenerek devreye alınabilecek bilinçli bir ödünleşimdir; varsayılan davranış değildir.
Degraded'in çoğu kurulum için doğru varsayılan olmasının nedeni budur: bir API istemcisi ya da Secret Manager kimlik bilgisi üzerinden token alan tipik entegrasyonlarda iptal zaten kesim noktasıyla tam ve anında etkilidir. Strict mod yalnızca yukarıdaki iki dar, eski-tip yolu kapsayan ek bir güvenlik katmanı sunar — bunu yalnızca o iki yoldaki her token doğrulamasında bir cache bağımlılığı ve kesinti riskiyle satın alır.
Bu ayar kurulum genelinde tektir; proje, politika veya ortam bazında ayrı ayrı yapılandırılamaz.