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
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- 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ı?
- 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.
- 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.
- 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ıysa0olacak ş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: 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 4: 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 5: 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 6: 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 7: 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 8: 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. |
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. |