Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) üzerinden hedef sistemden gelen SOAP yanıtlarının bütünlüğünü dijital imza doğrulamasıyla garanti eder.
- Şifreli SOAP gövdelerini yapılandırılmış keystore bilgileriyle çözerek arka uçtan gelen hassas verilerin doğru şekilde iletilmesini sağlar.
- Politika koşulları sayesinde belirli endpoint veya header kombinasyonlarında WS-Security doğrulama gerekliliklerini zorunlu kılar.
- Özelleştirilebilir hata mesajlarıyla entegrasyon hatalarında operasyon ekiplerinin kök neden analizi yapmasını kolaylaştırır.
Ç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 Security From Target 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 Doğrulaması: Seçilen truststore ile dijital imza doğrulaması, ardından şifre açma keystore’uyla SOAP gövdesi çözülür; keystore bulunamazsa işlem hata verir.
- Karar Verme:
- Eşleşme Var: SOAP yanıtı doğrulanır, gerekirse şifresi açılır ve istemciye iletilir.
- Eşleşme Yok: Doğrulama veya şifre açma başarısız olur ve tanımlı hata mesajı döndürülür.
- 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
- Şifre Açma Desteği: Hedef sistemden gelen şifreli SOAP gövdelerini seçilen keystore ile açar; alias ve parola bilgileri Worker Context üzerinden okunur.
- İmza Doğrulama Desteği: Truststore olarak tanımlanan keystore ile dijital imzaları doğrular, güvenilmeyen sertifikaları reddeder.
- Dinamik Politika Koşulları: Query Builder entegrasyonu ile endpoint, header veya IP tabanlı kural kombinasyonlarını yönetir.
- 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
- Çok Ortamlı Keystore Erişimi: Aktif proje bağlamındaki keystore ortamını otomatik seçer, Canlı Ortam geçişlerinde şeffaf çalışır.
- Case Insensitive İmza ID Opsiyonu: allowCaseInsensitiveId alanı etkinleştirildiğinde XML Signature ID değerlerini büyük/küçük harf duyarsız karşılaştırır.
- Politika Akışı Senkronizasyonu: Event Manager ile politika güncellemelerini gerçek zamanlı tetikler, global politika değişikliklerinde kullanıcıyı uyarır.
- 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ç |
|---|---|---|---|
| Hedef İmza Doğrulama | SOAP yanıtı imzalı geliyor | İmza Doğrulama toggle’ını aç, güvenilir truststore seç. | Yanıt doğrulanır, sahte imzalar 403 döndürür. |
| Şifre Çözme Gereken Servis | Hedef servis gövdeyi AES ile şifreliyor | Şifre Açma toggle’ını aç, ilgili keystore’u eşleştir. | Gövde çözülür, istemci düz metin alır. |
| Kritik Endpoint Koruması | Sadece /billing/* isteğinde kontrol isteniyor | Condition ile Path equals /billing/* tanımla. | Sadece kritik endpoint’te WS-Security denetimi yapılır. |
| Geçersiz Sertifika Engeli | Yanıt sahte sertifikayla geliyor | Güvenilir root içeren truststore seç. | Yanıt reddedilir, özelleştirilmiş hata mesajı döner. |
| Çoklu Ortam Yönetimi | Test ve Canlı Ortam farklı keystore kullanıyor | Ortama özel keystore ID’leriyle global politika kullan. | Deploy sonrası ortam bazlı keystore otomatik yüklenir. |
| Hata Mesajı Özelleştirme | Entegrasyon ekibi ayrıntılı mesaj istiyor | Error Message sekmesinde özel JSON tanımla. | 403 cevabı özel hata kodu ve açıklama içerir. |
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 Hedeften 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 Hedeften 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_WS_FromTarget- 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: “WS-Security doğrulama ve şifre açma” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Şifre Açma Parametrelerini Yapılandırma | - Şifre Açma (decExists) toggle’ını etkinleştirerek şifreli SOAP gövdelerinin çözüleceğini belirtin. - Şifre Açma Keystore listesinden uygun keystore ID’sini seçin. - Keystore henüz yoksa Add KeyStore diyaloğu ile yeni kayıt oluşturun. - Keystore seçilmediğinde politika geçersiz olur ve kaydetme engellenir. |
| Adım 4: İmza Doğrulama Parametreleri | - İmza Doğrulama (verExists) toggle’ını açarak dijital imzaların kontrolünü zorunlu kılın. - İmza Doğrulama Keystore alanında güvenilen sertifika deposunu seçin. - Truststore yalnızca kök/ara sertifikaları içermeli, özel anahtar bulunmamalıdır. - Yanıt imzası olmayan servisler için toggle kapalı bırakılabilir. |
| Adım 5: Keystore Yönetimi ve Senkronizasyonu | - Add KeyStore diyaloğu ile oluşturulan kayıtlar listeye otomatik eklenir. - Yeni keystore geldiğinde listeyi güncel tutmak için sayfayı yenilemeye gerek yoktur. - Alias ve parola bilgileri Worker Context üzerinden okunur; yanlış alias seçimi imza doğrulamasını başarısız kılar. - Gerektiğinde KeyStore diyaloğunu kapatarak seçimin form alanına işlendiğini doğrulayın. |
| 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 denetimi aktif. 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 |
|---|---|
| Şifre Açma ve Doğrulama Sırası | - Doğrulama, WSSecurityEngine ile başlar. - Başarılı imzadan sonra şifre açma devreye girer. - Her iki adım da başarısızsa politika hata üretir. |
| Case Insensitive ID Opsiyonu | - allowCaseInsensitiveId devredeyse imza ID karşılaştırmaları büyük/küçük harf duyarsız yapılır. - XML Signature öğesinde alternatif ID kullanımlarını destekler. - Yanlış yapılandırma imza doğrulamasını geçersiz kılabilir. |
| Dinamik Keystore Güncelleme | - Worker Context, aktif ortama göre keystore’u çözer. - Yeni keystore deploy edildiğinde politika ek işlem gerektirmeden güncel veriyi çeker. - Parola güncellemeleri anlık yansır. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Keystore Yönetimi | Kötü: Aynı keystore’u tüm ortamlarla paylaşmak. İyi: Ortam bazlı keystore oluşturmak. En İyi: Keystore’ları gizli yönetim sisteminden otomatik çekmek. |
| Politika Koşulları | Kötü: Koşulsuz tüm endpoint’lerde çalıştırmak. İyi: Kritik endpoint’leri filtrelemek. En İyi: Rate Limiting ile kombinleyerek saldırı yüzeyini azaltmak. |
| Hata Mesajı Yönetimi | Kötü: Varsayılan 403 mesajını değiştirmemek. İyi: Hatanın hangi adımda oluştuğunu belirtmek. En İyi: Operasyon referans kodu ve takip ID’si eklemek. |
| Çoklu Ortam Dağıtımı | Kötü: Canlı Ortam keystore’unu testte kullanmak. İyi: Ortam geçişlerinde export/import yapmak. En İyi: Deploy pipeline’ında otomatik import ve doğrulama çalıştırmak. |
| Test Stratejisi | Kötü: Sadece manuel test yapmak. İyi: SOAP UI scriptleriyle imza doğrulamak. En İyi: CI/CD pipeline’ında otomatik WS-Security regresyon testleri çalıştırmak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Truststore Hijyeni | Güvenilmeyen sertifikaları listeye eklemeyin; sertifika zincirini düzenli aralıklarla yenileyin. |
| Keystore Parolaları | Parolaları gizli kasada saklayın, kesinlikle kaynak kodda tutmayın. |
| Case Insensitive ID Kullanımı | Bu özelliği sadece hedef servis ID tutarsızlığı yaratıyorsa aktif edin; aksi halde gereksiz esneklik saldırı yüzeyini artırabilir. |
| Günlükleme | Hata durumlarında signature subject ve keystore alias bilgisini maskelenmiş olarak loglayın. |
| Yetkilendirme | Politika düzenleme yetkisini sadece WS-Security uzmanlığı olan kullanıcılara verin. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Varsayılan Keystore Kullanımı | Neden kaçınılmalı: Tüm ortamlar aynı anahtarı paylaşırsa güvenlik ihlali riski artar. Alternatif: Ortam bazlı keystore ve parola yönetimi uygulayın. |
| Tüm Denetimleri Kapama | Neden kaçınılmalı: Politika en az bir güvenlik adımı olmadan kaydedilemez; bypass denemeleri güvenlik açığı oluşturur. Alternatif: En az bir denetimi aktif bırakın, gerekiyorsa iki adımı da paralel çalıştırın. |
| Eksik Error Message | Neden kaçınılmalı: Hata mesajı boş bırakılırsa entegrasyon ekipleri kök nedeni bulamaz. Alternatif: Hata mesajına correlation ID ekleyin. |
| Sertifika Süresi Takipsizliği | Neden kaçınılmalı: Süresi dolan sertifika tüm istekleri reddeder. Alternatif: Sertifika bitiş tarihleri için uyarı mekanizması kurun. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| SOAP Mesaj Boyutu | Öneri: Gereksiz namespace ve whitespace’i azaltın. Etki: WS-Security işleme süresi düşer. |
| Keystore Boyutu | Öneri: Truststore’u sadece gerekli sertifikalarla sınırlayın. Etki: Yükleme ve doğrulama süresi azalır. |
| Thread Havuzu | Öneri: Gateway worker thread sayısını WS-Security işlem yüküne göre ayarlayın. Etki: Paralel SOAP doğrulama performansı artar. |
| Cache Kullanımı | Öneri: Sertifika zinciri doğrulamasında Gateway cache mekanizmasını etkinleştirin. Etki: Tekrarlayan imza doğrulamaları hızlanır. |
| Monitoring | Öneri: WS-Security hata oranlarını metrik olarak izleyin. Etki: Performans veya sertifika sorunları erken tespit edilir. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Politikayı yalnızca SOAP servislerinde mi kullanmalıyım? | Evet, WS Security From Target SOAP WS-Security standartlarını hedefler; REST servislerde etkisizdir. |
| Genel | En az bir denetimi neden aktif bırakmak zorundayım? | Politika amacına ulaşmak için imza doğrulama veya şifre açma yapılmalıdır; aksi durumda politika gereksizdir ve kaydetme engellenir. |
| Teknik | İmza doğrulama neden başarısız olabilir? | Yanlış truststore, süresi dolmuş sertifika veya farklı canonicalization algoritması nedeniyle olabilir; loglardaki PolicyWSSecurityFromException detaylarına bakın. |
| Teknik | Şifre açma için hangi keystore formatları destekleniyor? | JKS ve P12 türleri Worker Context üzerinden desteklenir; alias ve parola doğru olmalıdır. |
| Kullanım | Global politikayı local politikaya dönüştürebilir miyim? | Detay sayfasındaki Localize butonu ile global politika kopyalanarak API’ye özel hale getirilir. |
| Kullanım | Deploy öncesi nasıl kontrol yaparım? | Export edilen ZIP’i Development ortamına import ederek deneme yapabilir, SOAP UI ile imza/şifre testleri çalıştırabilirsiniz. |