WS-Security Timestamp

SOAP mesajlarına WS-Security Timestamp ekleyip mustUnderstand ve TTL ayarlarıyla yeniden oynatma saldırılarını engelleyebilirsiniz

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

​

Genel Bakış

​

Amacı Nedir?

• SOAP tabanlı isteklerde WS-Security Timestamp başlığını otomatik ekleyerek mesajların süre sınırını uygular ve tekrar saldırı alanını daraltır.
• MustUnderstand bayrağını opsiyonel olarak etkinleştirerek hedef servislerin güvenlik başlığını zorunlu olarak işlemesini sağlar.
• API Proxy (API Vekil Sunucusu) düzeyinde global veya local politika olarak tanımlanabildiği için yeniden kullanım ve merkezi yönetim sunar.
• Hata mesajlarını merkezi olarak özelleştirerek süre aşımı veya doğrulama sorunlarına dair tutarlı bildirim üretir.

​

Çalışma Prensibi

1. İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. Politika Kontrolü: WS Güvenliği Zaman Damgası (WS Security Timestamp) politikası aktif ise, sistem aşağıdaki sırayla kontrol yapar:
   • Condition (koşul) tanımlı mı? Varsa koşul sağlanıyor mu?
   • Politika aktif mi (active=true)?
   • Variable kullanılıyor mu yoksa Apinizer default mı?
3. WS-Security Timestamp Enjeksiyonu: SOAP zarfında Security header mevcut değilse oluşturulur, mustUnderstand parametresine göre işaretlenir ve Time To Live değeri saniye cinsinden uygulanarak Timestamp öğesi eklenir.
4. Karar Verme:
   • Eşleşme Var: Koşullar sağlandığında timestamp başlığı eklenir veya güncellenir; mesaj gövdesi yeni süre bilgisiyle hedefe yönlendirilir.
   • Eşleşme Yok: Koşullar sağlanmadığında SOAP gövdesi değiştirilmez ve politika zincirinde bir sonraki adıma geçilir.
5. Hata İşleme: Politika kuralına uymayan istekler için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür.

​

Özellikler ve Yetenekler

​

Temel Özellikler

• Dinamik Geçerlilik Süresi: Time To Live alanı ile timestamp’in kaç saniye geçerli olacağını tanımlayabilir, 0 değeri süre sınırı olmadan header üretir; değer girilmezse güvenli varsayılan olan 300 saniye uygulanır.
• MustUnderstand Zorunluluğu: SOAP güvenlik başlığının hedef servis tarafından mutlaka işlenmesini sağlamak için mustUnderstand bayrağını açıksa 1, kapalıysa 0 olacak şekilde yönetir.
• Otomatik Namespace Yönetimi: Politika, Security header namespace’ini ve eksik SOAP header bileşenlerini otomatik ekleyerek manuel XML düzenleme ihtiyaçlarını ortadan kaldırır.
• Aktif/Pasif Durum Kontrolü: Politikanın aktif veya pasif durumunu kolayca değiştirme (active/passive toggle). Pasif durumda politika uygulanmaz ancak yapılandırması saklanır.
• Koşul Bazlı Uygulama: Query Builder ile karmaşık koşullar oluşturarak politikanın ne zaman uygulanacağını belirleme (örn: sadece belirli endpoint’lere veya header değerlerine göre).

​

İleri Düzey Özellikler

• Varsayılan TTL Geri Dönüş Mekanizması: Negatif veya boş bırakılan Time To Live değerlerini otomatik olarak 300 saniyeye sabitleyerek güvenli başlangıç değerleri uygular.
• Security Header Üretimi: SOAP mesajında Security header bulunmadığında yeni header yaratır, mevcutsa mustUnderstand bayrağını güncelleyerek birleşik yönetim sağlar.
• Hata Yönetimi Entegrasyonu: WSSecurityException veya beklenmeyen hataları yakalayarak özelleştirilebilir hata kodları ve mesaj listeleriyle Apinizer olay yönetimine iletir.
• Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) import etme. Versiyon kontrolü ve yedekleme imkanı.
• Policy Group ve Proxy Group Desteği: Birden fazla politikayı Policy Group içinde yönetme. Proxy Group’lara toplu politika atama. Merkezi güncelleme ve deploy işlemleri.
• Deploy ve Versiyonlama: Politika değişikliklerini canlı ortama deploy etme. Hangi API Proxy’lerde kullanıldığını görme (Policy Usage). Proxy Group ve Policy Group kullanım raporları.

​

Kullanım Senaryoları

Senaryo	Durum	Çözüm (Politika Uygulaması)	Beklenen Davranış / Sonuç
SOAP Servis Replay Koruması	İş ortağı bankacılık servisi, yeniden oynatma saldırılarına karşı timestamp zorunluluğu ister.	Time To Live = 120, MustUnderstand = true.	2 dakika içinde gönderilen çağrılar kabul edilir, süresi dolan istekler özelleştirilmiş hata mesajı ile reddedilir.
İç Sistem Saat Uyumu	Kurum içi SOAP servisleri hafif saat sapmaları yaşar ve uzun ömürlü biletler gerektirir.	Time To Live = 0, MustUnderstand = false.	Timestamp eklenir ancak süre sınırı uygulanmaz; servisler isteği toleranslı biçimde işler.
Regülasyon Uyum Kontrolü	Finansal entegrasyon, WS-Security header’ında mustUnderstand=“1” bekler.	MustUnderstand = true, Time To Live = 60.	Regülatör kontrolleri geçer, header’ı yoksayan servisler hata ile uyarılır.
Çoklu WS-Security Zinciri	Aynı akışta WS-Security Signature ve Timestamp politikaları ardışık çalışır.	Timestamp politikası, imza politikasından önce konumlandırılır.	İmza işlemi timestamp’i kapsar, güvenlik doğrulamaları aynı header altında toplanır.
Geliştirme Ortamı Testi	Geliştirme ortamında entegrasyon ekipleri timestamp’e bağlı hata senaryolarını doğrulamak ister.	Time To Live = 30, MustUnderstand = false, özel hata kodu tanımlı.	Kısa süreli TTL ile hata üretimi kolaylaşır, test raporları standart hatalarla zenginleşir.
SOAP Gateway Konsolidasyonu	Farklı SOAP servislerine tek proxy üzerinden erişilir ve merkezi güvenlik başlığı gereklidir.	Global politika olarak etkin, Query Builder ile /payment/* endpoint’lerine koşul eklenir.	İlgili endpoint’lere gelen tüm istekler ortak timestamp kuralına uyar, diğer endpoint’ler etkilenmez.

​

Politika Parametrelerini Yapılandırma

Bu adımda, kullanıcı yeni bir politika oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilir. Tanımlanan parametreler, politikanın çalışma şeklini (örneğin hangi IP’lerin izinli olacağı, coğrafi kısıtlamalar, koşullu aktivasyonlar vb.) doğrudan etkiler. Bu sayede politika hem kuruma özel gereksinimlere göre özelleştirilebilir hem de merkezi olarak yönetilebilir.

​

Yeni WS Güvenliği Zaman Damgası Politikası Oluşturma

​

Yapılandırma Adımları

Adım	Açıklama / İşlem
Adım 1: Oluşturma Sayfasına Gitme	- Sol menüden Development → Global Settings → Global Policies → WS Güvenliği Zaman Damgası bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın.
Adım 2: Temel Bilgileri Girme	Policy Status (Politika Durumu): Aktif/Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Name (İsim) Zorunlu: Örnek: Production_WsSecurityTimestamp - Benzersiz isim girin, boşlukla başlamaz. - Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim. Description (Açıklama): Örnek: “SOAP istekleri için timestamp zorunlu.” - Maks. 1000 karakter. - Politikanın amacını açıklayın.
Adım 3: Variable Kullanımı	- Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz. - Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. - Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar. - Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Adım 4: WS-Security Timestamp Parametreleri	- Time To Live (saniye): Timestamp’in geçerlilik süresini tanımlar; boş bırakılırsa varsayılan 300 saniye uygulanır. - TTL değerini mümkün olduğunca düşük tutarak tekrar saldırısı riskini azaltın. - 0 değeri süre sınırı olmadan timestamp oluşturur; sadece saat senkronizasyonu güçlü ortamlarda tercih edin.
Adım 5: Must Understand Bayrağı (Varsa)	- Onaylandığında SOAP Security header’ı mustUnderstand="1" olarak işaretler. - Hedef servis header’ı işleyemezse isteği reddeder; tüm entegrasyonların bu davranışı desteklediğini doğrulamadan etkinleştirmeyin.
Adım 6: Ek Güvenlik Başlıkları (Varsa)	- Bu politika ekstra parametre gerektirmez; ilave WS-Security ihtiyaçları için imzalama veya şifreleme politikalarıyla birleştirin. - İhtiyaç olduğunda politikayı diğer WS-Security bileşenleriyle zincirleyerek güvenliği katmanlı hale getirebilirsiniz.
Adım 7: Koşul Tanımlama (İsteğe Bağlı)	- Condition sekmesine geçin. - Koşullar, politikanın hangi durumda aktif olacağını belirler. Örnekler: - Ortam bazlı: Header = X-Environment, Operator = Equals, Value = production - API Key bazlı: Header = X-API-Key, Starts With = PROD- - Endpoint bazlı: Path = /api/admin/* Koşul tanımlamazsa politika her zaman aktif Detaylar için bakabilirsiniz: Koşullar (Conditions)
Adım 8: Hata Mesajı Özelleştirme (İsteğe Bağlı)	- Error Message Customization sekmesine gidin. - Erişim reddedildiğinde dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 403, "message": "[Default hata mesajı]" } Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" }
Adım 9: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir WS-Security konfigürasyonu mevcut Sonuç: - Politika listeye eklenir. - API’lere bağlanabilir. - Global politikaysa otomatik uygulanır.

Koşullar ve Hata Mesajı Özelleştirme panellerinin açıklaması için Politika Nedir? sayfasındaki Koşullar ve Hata Mesajı Özelleştirme (Error Message Customization) bölümlerini inceleyebilirsiniz.

Hata mesajı yapılandırmasının tüm katmanları, öncelik sırası ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

​

Politikayı Silme

Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Yönetimi sayfasındaki Akıştan Politika Kaldırma bölümüne bakabilirsiniz.

​

Politikayı Dışa/İçe Aktarma

Bu politikanın dışa aktarma (Export) ve içe aktarma (Import) adımları için Export/Import sayfasına bakabilirsiniz.

​

Politikayı API’ye Bağlama

Bu politikanın API’lere nasıl bağlanacağına ilişkin süreç için Politika Yönetimi sayfasındaki Politikayı API’ye Bağlama bölümüne bakabilirsiniz.

​

İleri Düzey Özellikler

Özellik	Açıklama ve Adımlar
SOAP Header Tutarlılık Denetimi	- SOAP zarfları taranarak mevcut Security header olup olmadığı kontrol edilir. - Header yoksa otomatik eklenir. - MustUnderstand değeri, politika ayarına göre güncellenir.
TTL Fallback İşleyişi	- Negatif veya boş Time To Live değerleri algılanır. - Varsayılan 300 saniye değeri uygulanır. - Güncellenen değer loglanarak hata analizi kolaylaştırılır.
Hata Mesajı Özelleştirme İş Akışı	- Error Message sekmesinde yeni şablon oluşturulur. - HTTP durum kodu, hata kodu ve mesaj alanları doldurulur. - Deploy öncesi test çağrılarıyla mesaj formatı doğrulanır.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Zaman Senkronizasyonu	Kötü: NTP olmayan sunucularda TTL’i yüksek bırakmak. İyi: Sunucular arası NTP senkronizasyonu sağlamak. En İyi: NTP izleme alarmlarıyla TTL ≤ 120 saniyeyi standartlaştırmak.
Time To Live Yönetimi	Kötü: 0 değerini tüm ortamlarda kullanmak. İyi: Geliştirme/test ortamında yüksek TTL, Canlı Ortam’da düşük TTL belirlemek. En İyi: Risk sınıfına göre TTL’i 30-120 saniye aralığında otomatik ayarlayan politika varyantları kullanmak.
MustUnderstand Kullanımı	Kötü: Tüm entegrasyonlarda mustUnderstand’i zorunlu kılmak. İyi: Hedef servis yetkinliklerini doğruladıktan sonra etkinleştirmek. En İyi: Servislerin WS-Security uyumluluğunu sözleşmelerde belgeleyip mustUnderstand’i sadece teyitli entegrasyonlarda açmak.
Hata Mesajı Tasarımı	Kötü: Varsayılan 500 hatasını aynen bırakmak. İyi: Hata kodunu özelleştirip açıklayıcı mesaj eklemek. En İyi: İzleme araçlarıyla entegre, JSON yapısında detaylı hata şablonları oluşturmak.
Politika Dağıtım Sırası	Kötü: Timestamp politikasını imzalama veya şifreleme politikalarından sonra çalıştırmak. İyi: Güvenlik politikasını imza öncesi konumlandırmak. En İyi: Politika akışını standartlaştırıp tüm proxy’lerde aynı sırayı otomatik enforce etmek.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Saat Kaynağı Yönetimi	Tüm gateway ve backend sunucularında güvenilir NTP kaynakları kullanın; zaman kayması timestamp doğrulamasını geçersiz kılar.
Çok Katmanlı WS-Security	Timestamp politikasını imzalama ve şifreleme politikalarıyla birlikte kullanarak mesaj bütünlüğünü güçlendirin.
Hata Mesajı Hijyeni	Hata mesajlarında sistem iç ayrıntıları paylaşmayın; sadece izleme için gerekli kodları ekleyin.
Koşul Bazlı Etkinleştirme	Yalnızca WS-Security gerektiren endpoint’lerde aktif olacak koşullar tanımlayarak gereksiz yükü azaltın.
Versiyon Kontrolü	Politika değişikliklerini export ederek sürümleyin ve Canlı Ortam’a taşımadan önce test edin.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
TTL’yi Aşırı Yüksek Tutmak	Neden kaçınılmalı: Uzun geçerlilik süreleri replay saldırısı riskini artırır. Alternatif: TTL’i risk seviyesine göre 30-300 saniye arasında tutun.
MustUnderstand’i Körü Körüne Açmak	Neden kaçınılmalı: Uyumlu olmayan servisler isteği reddedebilir. Alternatif: Uyum doğrulaması yaptıktan sonra etkinleştirin.
Koşul Tanımlamamak	Neden kaçınılmalı: Gereksiz tüm isteklerde ek yük oluşturur. Alternatif: Endpoint veya header bazlı koşullar tanımlayın.
Hata Mesajını Varsayılan Bırakmak	Neden kaçınılmalı: Sorun giderme zorlaşır. Alternatif: İzlenebilir hata kodları ve insan tarafından okunabilir açıklamalar girin.

​

Performans İpuçları

Kriter	Öneri / Etki
Time To Live Değeri	Öneri: TTL’i ihtiyaca göre kısaltın. Etki: Daha az XML manipülasyonu ve daha az süreli cache yükü.
Koşul Kullanımı	Öneri: Query Builder ile sadece gerekli endpoint’leri hedefleyin. Etki: Politika gereksiz SOAP mesajlarında çalışmaz, CPU tasarrufu sağlar.
Politika Sıralaması	Öneri: Timestamp’i imzalama politikalarından önce yerleştirin. Etki: İmza işlemi tek seferde yapılır, tekrar işlem maliyeti düşer.
Hata Şablonları	Öneri: Hafif JSON hata şablonları kullanın. Etki: Ağ üzerinden daha küçük payload iletilir.
Monitoring Entegrasyonu	Öneri: Politika loglarını merkezi izleme ile toplayın. Etki: Sorun anında TTL ayarlarını optimize etmek mümkün olur.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Time To Live değeri boş bırakılırsa ne olur?	Değer girilmezse politika otomatik olarak 300 saniyelik güvenli varsayılanı uygular ve bu bilgi detay ekranında görüntülenir.
Genel	0 değeri gerçekten sınırsız mı?	0 girildiğinde timestamp eklenir ancak süre sınırı uygulanmaz; saat senkronizasyonu güçlü ortamlarda önerilir, aksi halde süre sınırlı değer seçin.
Teknik	MustUnderstand açıkken hata alıyorum, neden?	Hedef servis WS-Security header’ını işleyemiyorsa isteği reddeder; entegrasyon takımından mustUnderstand desteği talep edin veya bayrağı kapatın.
Teknik	Politikayı REST endpoint’lerinde kullanabilir miyim?	Politika SOAP zarfı üzerinde çalışır; REST JSON isteklerinde etkisi olmaz, bu nedenle sadece SOAP tabanlı endpoint’lerde etkinleştirin.
Kullanım	Global politikayı local’e çevirmek mümkün mü?	Detay ekranındaki [Localize] butonu ile global politikadan local kopya oluşturabilir, API bazlı ayarlamalar yapabilirsiniz.
Kullanım	Hata mesajlarını nasıl özelleştiririm?	Update sayfasındaki Error Message Customization sekmesinden durum kodu, hata kodu ve mesaj alanlarını düzenleyerek yeni şablon kaydedin.