WS-Security Decrypt

Gelen SOAP mesajlarındaki WS-Security şifreli içerikleri seçilen anahtar deposu ile çözebilirsiniz

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?

• WS-Security ile şifrelenmiş SOAP mesajlarını API Proxy (API Vekil Sunucusu) katmanında çözerek uygulamaya düz metin içerik iletilmesini sağlar.
• Mesaj şifre çözme anahtarlarını merkezi bir anahtar deposunda yönetip yetkisiz erişimleri engeller.
• Koşul bazlı etkinleştirme ile yalnızca belirli Endpoint akışlarında şifre çözme işlemi çalıştırılır.
• Özelleştirilebilir hata mesajlarıyla tüketici uygulamalara anlamlı geri bildirim sunar.

​

Ç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üvenlik Şifre Çözme 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. Şifre Çözme Kontrolü: SOAP zarfındaki WS-Security EncryptedData blokları incelenir, seçilen anahtar deposundan özel anahtar alınır ve mesaj içeriği çözümlenir.
4. Karar Verme:
   • Eşleşme Var: Anahtar deposundaki anahtar ile şifre çözülür ve mesaj içeriği arka uç servise düz metin olarak iletilir.
   • Eşleşme Yok: Anahtar ID uyuşmazlığı veya eksik WS-Security header durumda politika başarısız olur, isteğin devamı durdurulur.
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

• SOAP Şifre Çözme Motoru: WS-Security standardındaki EncryptedKey ve EncryptedData bloklarını analiz eder, keystore’dan anahtar çekerek içeriği çözümleyip mesajı günceller.
• Anahtar Deposu Entegrasyonu: Kuruma özel KeyStore servisinden keystore listeler, seçilen deposu politika ile ilişkilendirir ve projeye göre filtreler.
• Esnek Hata Yönetimi: Varsayılan ve özelleştirilmiş hata mesajlarıyla şifre çözme hatalarında ayrıntılı geri bildirim sunar.
• 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

• Case-Insensitive Anahtar Eşleştirme: allowCaseInsensitiveId seçeneğiyle şifreli bloklardaki KeyIdentifier değerlerini büyük/küçük harf duyarlılığından bağımsız eşler.
• Global/Local Politika Akışı: Aynı yapılandırmayı global olarak paylaşıp local kopyalarla özelleştirme, localizasyon sırasında otomatik isim eşsizliği kontrolü.
• Eşzamanlı Kullanım Takibi: Politikayı kullanan API ve Proxy Group listesini göstererek değişiklik veya silme öncesi etki analizi sağlar.
• 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 Güvenli Trafik	Dış sisteme ait SOAP mesajları WS-Security ile şifreli geliyor	Global politikada projeye ait ProductionDecryptKS keystore seçilir.	Mesaj içeriği çözülür, arka uç servis şifreli veri görmez.
Bölümlü Şifre Kaldırma	Yalnızca yönetim servisi için şifre çözme gerekli	Koşulda Path = /api/admin/* tanımlanır.	Yönetim çağrıları çözülür, diğerleri atlanır.
Anahtar Rotasyonu	Yeni sertifika devreye alınacak	Yeni keystore oluşturulup politikada güncellenir.	Kesinti olmadan yeni anahtar kullanılır.
Case ID Uyumsuzluğu	Tedarikçi sistem KeyIdentifier değerlerini farklı case ile gönderiyor	allowCaseInsensitiveId etkinleştirilir.	Anahtar ID farkları tolere edilir, hata düşmez.
Test Ortamı İzolasyonu	Test ortamında farklı keystore kullanılmalı	Local politika oluşturulup ilgili API’ye atanır.	Test anahtarı yalnızca o API’de kullanılır.
Hata Analizi	Şifre çözme başarısız olduğunda anlamlı bildirim gerekli	Özel hata mesajı yapılandırılır, 403 statü kodu seçilir.	İstemciye açıklayıcı JSON hata döner.
Performans İzleme (opsiyonel)	Büyük mesajlarda şifre çözme maliyetli	Koşulda içerik tipine göre politika devre dışı bırakılır.	Gereksiz decryption engellenir, gecikme azalır.

​

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üvenlik Şifre Çözme 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üvenlik Şifre Çözme 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_WsDecrypt - 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: “Bankacılık entegrasyonları için SOAP şifre çözme” - 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 Decryption Parametreleri	Decryption KeyStore (Zorunlu): Listeden ilgili keystore’u seçin. Keystore, şifre çözme anahtarını içerir. KeyStore Tooltipleri: Seçilen kaynağın proje kapsamına uygun olduğunu doğrular.
Adım 5: Case-Insensitive ID Kontrolü (Varsa)	Allow Case-Insensitive Identifier: İşaretleyerek KeyIdentifier alanlarının büyük/küçük harf farkını göz ardı edin. SOAP sağlayıcısı farklı case kullanıyorsa aktive edin.
Adım 6: Şifre Çözme Doğrulama Notları (Varsa)	Test ortamında manuel olarak SOAP mesajını gönderip hata loglarını kontrol edin; yanlış keystore seçimi durumunda hata kodu 401 döner.
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 anahtar yapılandırması 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
KeyStore Yedekleme Entegrasyonu	- Keystore servisinde versiyon etiketi tanımlayın. - Politika kaydederken doğru etiketi seçin. - Rotasyon sonrası eski anahtarı export ile arşivleyin.
Çok Katmanlı Koşul Yönetimi	- Query Builder’da AND/OR bloklarını kullanın. - Header ve Path kombinasyonlarıyla SOAP dışı istekleri hariç tutun. - Koşul metnini preview ile doğrulayın.
Hata Senaryosu Test Otomasyonu	- Error Message sekmesinde özel kod tanımlayın. - Test otomasyonunda bu kodu doğrulayın. - Başarısız denemeleri Apinizer loglarında takip edin.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Anahtar Yönetimi	Kötü: Tek keystore’ı tüm ortamlarla paylaşmak. İyi: Ortam bazlı ayrı keystore’lar kullanmak. En İyi: Ortam + kullanım amacı (işlem tipi) bazlı segmentasyon sağlamak.
Koşul Tasarımı	Kötü: Koşul tanımlamadan tüm trafiğe uygulamak. İyi: Path bazlı filtre eklemek. En İyi: Path + Header + Method kombinasyonu ile minimum kapsam belirlemek.
Hata Görünürlüğü	Kötü: Varsayılan hata mesajını değiştirmemek. İyi: Genel hata mesajı eklemek. En İyi: Hata kodunu ve destek iletişim bilgisini içeren JSON mesajı tanımlamak.
Sürüm Yönetimi	Kötü: Değişiklikleri takip etmeden düzenlemek. İyi: Değişiklikleri manuel dokümante etmek. En İyi: Export dosyalarını sürüm kontrolüne alıp değişiklik tarihçesi çıkarmak.
Test Süreçleri	Kötü: Canlı Ortam üzerinde test yapmak. İyi: Test ortamında manuel doğrulama yapmak. En İyi: Otomasyon scriptleriyle şifre çözme ve hata senaryolarını düzenli test etmek.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Anahtar Saklama	Keystore erişim yetkilerini kısıtlayın, anahtar dosyalarını şifreli depolama alanında tutun.
Sertifika Rotasyonu	Sertifika yenileme takvimi oluşturun, rotasyon öncesi yeni keystore’u import edin ve politikayı hazırlayın.
Koşul Güvenliği	Koşulları yalnızca güvenilir trafiğe göre yapılandırın, açık wildcard kullanmamaya çalışın.
Audit Logları	Şifre çözme hatalarını ve başarı olaylarını loglayıp SIEM’e yönlendirin.
Yetki Denetimi	Politika düzenleme ve deploy işlemlerini ROLE_MANAGE_GLOBAL_POLICIES ile sınırlayın.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Yanlış Keystore Seçimi	Neden kaçınılmalı: Hatalı anahtar ile şifre çözme başarısız olur, 401 döner. Alternatif: Keystore adını ortam adına göre standartlaştırıp seçimde doğrulayın.
Koşulsuz Uygulama	Neden kaçınılmalı: Şifreli olmayan mesajlarda gereksiz işlem yükü oluşur. Alternatif: WS-Security header kontrolü yapan koşul ekleyin.
Pasif Politika Takibi	Neden kaçınılmalı: Gerekli olduğunda politika devre dışı kalmış olabilir. Alternatif: Passive politikaları düzenli gözden geçirin, gerekirse silin.
Hata Mesajı Gizliliği	Neden kaçınılmalı: Fazla teknik detay sızabilir. Alternatif: Genel mesaj verip ayrıntıyı loglarda tutun.

​

Performans İpuçları

Kriter	Öneri / Etki
Mesaj Boyutu	Öneri: Büyük SOAP gövdeleri için sıkıştırmayı etkinleştirin. Etki: Şifre çözme sonrası aktarım süresi kısalır.
Koşul Değerlendirmesi	Öneri: Koşullarda gereksiz regex kullanmayın. Etki: Politika değerlendirme süresi azalır.
Keystore Erişimi	Öneri: Keystore servisinin Cache süresini ayarlayın. Etki: Anahtar erişiminde gecikme azalır, throttle riski düşer.
Eşzamanlı İstekler	Öneri: Throttling ve Rate Limiting politikalarıyla birlikte kullanın. Etki: Ani yüklenmelerde şifre çözme kuyruğu yönetilir.
Log Seviyesi	Öneri: Debug loglarını yalnızca Geliştirme ortamında açın. Etki: Canlı Ortam performansı korunur.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	WS Güvenlik Şifre Çözme politikası hangi mesaj türlerini destekler?	Politikayı SOAP tabanlı WS-Security EncryptedData ve EncryptedKey yapıları için kullanabilirsiniz; REST JSON mesajları desteklenmez.
Genel	Politika pasif hale getirildiğinde ne olur?	Politika koşulları çalışmaz, şifre çözme yapılmaz; yapılandırma saklanır ve yeniden aktive edilebilir.
Teknik	allowCaseInsensitiveId ne zaman aktif edilmeli?	Dış sistem KeyIdentifier değerlerini farklı büyük/küçük harf varyasyonlarıyla gönderiyorsa uyumsuzluğu gidermek için aktif edin.
Teknik	Keystore değişikliği sonrası deploy gerekiyor mu?	Global politika için evet; değişiklik kaydedildikten sonra deploy edip bağlı API Proxy’lerde güncellenmesini sağlayın.
Kullanım	Aynı API üzerinde birden fazla WS Güvenlik Şifre Çözme politikası kullanılabilir mi?	Aynı akışta yalnızca bir politika etkin olmalıdır; farklı Endpoint’ler için local kopyalar oluşturabilirsiniz.
Kullanım	Hata mesajını nerede özelleştirebilirim?	Politika formundaki Error Message Customization sekmesinde statü kodu ve JSON gövdesini düzenleyebilirsiniz.