WS-Security Şifreleme

SOAP mesajlarındaki kritik bölümleri belirlenen sertifika ve algoritmalarla şifreleyebilirsiniz

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 Şifreleme politikası, SOAP tabanlı entegrasyonlarda hassas alanların hedef sistemin beklediği sertifika setiyle şifrelenmesini zorunlu kılarak veri gizliliğini sağlar.
• Politika, seçilebilir şifreleme algoritmaları ve anahtar tanımlayıcı tipleriyle kurumsal standartlara uyumlu, yeniden kullanılabilir bir güvenlik katmanı sunar.
• API Proxy (API Vekil Sunucusu) üzerinden geçen servis mesajlarında parça bazlı şifreleme yaparak, alanlara göre farklılaştırılmış koruma stratejilerinin uygulanmasına imkan tanır.
• mustUnderstand bayrağı ve koşul bazlı uygulama desteğiyle, yalnızca hedef sistemin WS-Security desteği olan çağrılarda uygulanan, esnek ve kontrollü bir güvenlik mekanizması oluşturur.

​

Çalışma Prensibi

1. İstek Gelişi: WS-Security Şifreleme politikası, API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. Politika Kontrolü: WS-Security Şifreleme 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 Şifreleme Kontrolü: Politika, seçilen keystore içindeki sertifikayı kullanarak encPartList’te tanımlanan XML elemanlarını veya içeriklerini, belirlenen encodeType ve algoritmalarla şifreler.
4. Karar Verme:
   • Eşleşme Var: Tüm parçalar başarıyla şifrelenir, SOAP zarfı güncellenir ve hedef endpoint’e gönderilir.
   • Eşleşme Yok: Politika uygulanmaz, istek orijinal haliyle iletilir.
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

• Sertifika Tabanlı Şifreleme: Kurumsal keystore’larda tutulan X.509 sertifikaları seçilerek, hedef sistemin beklediği public key ile şifreleme yapılır.
• Esnek Şifreleme Algoritmaları: AES 128/192/256-CBC ve RSA/RSA-OAEP gibi yaygın WS-Security algoritmaları arasından seçim yapılabilir.
• Hedef Parça Yönetimi: Namespace ve eleman adıyla belirlenen XML parçaları içerik veya eleman düzeyinde şifrelenebilir.
• 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

• mustUnderstand Zorlaması: SOAP header’da mustUnderstand bayrağı işaretlenerek hedef servisin WS-Security bloğunu mutlaka işlemesi sağlanır.
• Embedded Key Name Yönetimi: Embedded Key Info seçildiğinde, anahtar adı tanımlanarak hedef sistemin özel gereksinimleri karşılanır.
• Çoklu Parça Konfigürasyonu: Birden fazla SOAP Segment’i eşzamanlı şifreleyerek karmaşık mesaj şablonlarını destekler.
• 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ç
Finans SOAP Servisi	Finansal kredi hesaplama servisi, müşteri TCKN alanını şifreli bekliyor.	Keystore’dan ilgili sertifika seçilir, CustomerInfo elemanı ELEMENT olarak encPartList’e eklenir.	SOAP zarfındaki müşteri bilgisi şifrelenir, hedef sistem gerekliliği sağlanır.
Sağlık Bilgi Paylaşımı	Sağlık verileri taşıyan SOAP mesajı hassas alanları içeriyor.	MedicalRecord elemanı CONTENT olarak işaretlenir, AES-256 seçilir.	İçerik yalnızca hedef sistemde çözülebilir, veri gizliliği korunur.
Çoklu Endpoint Yönetimi	Aynı politikayı farklı API Proxy’lerde kullanma ihtiyacı var.	Global politika oluşturulur, Policy Group üzerinden ilgili API Proxy’lere atanır.	Merkezi yönetim sağlanır, güncellemeler tek noktadan yayılır.
İmzalı ve Şifreli Mesaj	Hedef sistem hem imza hem şifreleme bekliyor.	WS-Security Şifreleme politikası şifreleme kısmını üstlenir, ek olarak WS-Security Signature politikası uygulanır.	Birlikte kullanım sayesinde bütünlük ve gizlilik sağlanır.
Test Ortamında Geçici Anahtar	Test ortamı için farklı keystore gerekiyor.	Import ile test ortamına kopyalanır, encKeyStoreId test keystore’unu gösterecek şekilde güncellenir.	Ortama özgü sertifika ile şifreleme devam eder, canlı konfigürasyon korunur.
mustUnderstand Zorunluluğu	Hedef SOAP sunucusu WS-Security header’ının zorunlu olduğunu belirtiyor.	mustUnderstand işaretlenir, başarısız durumda özel hata mesajı tanımlanır.	Hedef servis header’ı işlemiyorsa hata döner, sorun hızlıca tespit edilir.
İçerik Bazlı Koşul	Sadece belirli operasyonlarda şifreleme gerekli.	Condition’da SOAPAction header’ı kontrol edilerek ilgili operasyonlar için politika uygulanır.	Gereksiz şifreleme engellenir, performans optimize edilir.

​

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-Security Şifreleme 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-Security Şifreleme 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_WSS_Encrypt - 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: “Finans SOAP çağrıları için WS-Security şifreleme ayarları” - 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: Şifreleme Anahtarı ve Tanımlayıcıyı Seçme	- Key Store listesinden hedef ortama ait sertifikayı seçin. - Key Identifier Type alanında sertifikanın mesajda nasıl referanslanacağını belirleyin (örn. ISSUER_NAME_AND_SERIAL_NUMBER). - Embedded Key Info seçildiğinde Embedded Key Name alanına hedef sistemin beklediği anahtar adını yazın.
Adım 5: Algoritmaları ve mustUnderstand Bayrağını Ayarlama (Varsa)	- Symmetric Encoding Algorithm ile içerik şifreleme algoritmasını seçin (AES-128/192/256). - Key Encryption Algorithm ile simetrik anahtarın hangi yöntemle sarılacağını belirleyin (RSA veya OAEP). - mustUnderstand kutusunu işaretleyerek SOAP header’ının hedef tarafından zorunlu olarak işlenmesini sağlayın.
Adım 6: Şifreleme Parçalarını Tanımlama (Varsa)	- Add butonuna tıklayarak encPartList’e yeni kayıt ekleyin. - Name alanına şifrelenecek elemanın QName’ini (prefix hariç) yazın. - Namespace alanı ile hedef namespace’i tanımlayın (opsiyonel). - Encode Type olarak CONTENT (yalnızca içerik) veya ELEMENT (tam düğüm) seçin. - Her çağrı için en az bir parça tanımlamak zorunludur.
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 şifrelenmiş parça 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
Sertifika Rotasyonu	- Yeni sertifikayı keystore’a ekleyin. - Politika üzerinde encKeyStoreId’yi güncelleyin. - Deploy ederek tüm bağlı API Proxy’lerde sertifika değişikliğini etkinleştirin.
Çoklu Parça Şifreleme Stratejisi	- encPartList’e farklı elemanlar ekleyin. - Her eleman için uygun Encode Type seçin. - Test çağrılarıyla şifrelenen alanların hedefte doğru çözüldüğünü doğrulayın.
mustUnderstand ile Uyum Testi	- mustUnderstand bayrağını aktif edin. - Hedef servisin WS-Security bloğunu işleme kapasitesini doğrulayın. - Hata durumunda özelleştirilmiş SOAP Fault mesajı sağlayın.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Sertifika Yönetimi	Kötü: Süresi dolan sertifikaları üretimde fark etmek. İyi: Keystore sertifika son kullanma tarihlerini manuel takip etmek. En İyi: Sertifika yenilemelerini CI/CD pipeline’ına dahil edip otomatik bildirim almak.
Algoritma Seçimi	Kötü: Varsayılan AES-128 algoritmasını tüm entegrasyonlarda kullanmak. İyi: Kritik uygulamalarda AES-256 tercih etmek. En İyi: Hedef sistem desteğine göre güçlü algoritmaları zorunlu kılan politika grupları oluşturmak.
Parça Belirleme	Kötü: Tüm SOAP zarfını şifrelemek. İyi: Hassas alanları CONTENT olarak şifrelemek. En İyi: Hedef sistem gerekliliklerine göre ELEMENT ve CONTENT karışımıyla minimal ama yeterli şifreleme yapmak.
mustUnderstand Kullanımı	Kötü: mustUnderstand bayrağını gereksiz yere açık bırakmak. İyi: Hedef sistemin WS-Security desteğini doğruladıktan sonra açmak. En İyi: QA ortamında mustUnderstand kombinasyonlarını test edip, üretime yalnızca doğrulanmış entegrasyonlarda taşımak.
Ortamlar Arası Yönetim	Kötü: Her ortamda manuel politika güncellemek. İyi: Export/Import ile konfigürasyonu taşımak. En İyi: Politika versiyonlarını Git deposunda saklayıp pipeline ile ortamlara dağıtmak.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Keystore Erişimi	Keystore kullanıcı yetkilerini minimal tutun, sadece ihtiyaç duyan rollere okuma izni verin.
Sertifika Doğruluğu	Sertifikanın fingerprint ve issuer bilgilerini hedef sistemle eşleştirerek doğrulayın.
Algoritma Güncelliği	Güvenlik bültenlerini takip ederek zayıflayan algoritmaları hızla güncelleyin.
Hata Mesajı İçeriği	Özelleştirilmiş hata mesajlarında teknik detay açığa çıkarmayın, sadece takip için gerekli kodları yayın.
Politika Kullanım Denetimi	Policy Usage ekranından düzenli olarak hangi API Proxy’lerin politikayı kullandığını denetleyip yetkisiz atamaları kaldırın.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Yanlış Namespace Kullanımı	Neden kaçınılmalı: Namespace hatası, şifrelenmeyen alan bırakır. Alternatif: XML örneğini inceleyip tam namespace URI’sini kullanın.
Keystore ID Boşluğu	Neden kaçınılmalı: Sertifika bulunamadığında politika 500 hatası üretir. Alternatif: Kaydetmeden önce zorunlu alan doğrulamasından geçin.
Uyumsuz Algoritma Seçimi	Neden kaçınılmalı: Hedef sistem şifreyi çözemeyebilir. Alternatif: Karşı tarafın desteklediği algoritma listesini doğrulayın.
mustUnderstand Yanlış Kullanımı	Neden kaçınılmalı: Header işlenmediğinde SOAP Fault oluşur. Alternatif: mustUnderstand yalnızca gerçekten zorunlu entegrasyonlarda etkinleştirin.

​

Performans İpuçları

Kriter	Öneri / Etki
Keystore Erişim Sıklığı	Öneri: Keystore’ları bellek önbelleği ile kullanın. Etki: Şifreleme sırasında gecikme azalır.
Parça Sayısı	Öneri: Sadece gerekli XML düğümlerini şifreleyin. Etki: CPU kullanımı düşer, throughput artar.
Algoritma Seçimi	Öneri: Güvenlik politikası izin veriyorsa AES-128 kullanın. Etki: Şifreleme süresi kısalır.
Koşullandırma	Öneri: Condition ile gereksiz çağrılarda politikayı devre dışı bırakın. Etki: SOAP mesajı çevirme maliyeti düşer.
Politika Grubu Yönetimi	Öneri: Aynı şifreleme gereksinimlerini tek Policy Group altında toplayın. Etki: Yönetim maliyeti düşer, dağıtım hızlanır.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	WS-Security Şifreleme politikası hangi senaryolarda zorunlu?	Hassas verilerin SOAP ile taşındığı ve hedef sistemin şifrelenmiş alan beklediği tüm entegrasyonlarda zorunludur.
Genel	Politika local olarak oluşturulabilir mi?	Evet, Localize butonu ile global konfigürasyon kopyalanarak API bazlı local politika yaratılabilir.
Teknik	Encode Type CONTENT ile ELEMENT arasındaki fark nedir?	CONTENT sadece elemanın içeriğini şifreler, ELEMENT ise elemanı namespace dahil tamamıyla sarar.
Teknik	mustUnderstand bayrağı şifrelemeyi nasıl etkiler?	mustUnderstand sadece SOAP header’ın zorunlu işlenmesini sağlar; şifreleme sürecini değiştirmez ancak hedefin uyumsuzluğu halinde SOAP Fault üretir.
Kullanım	Keystore değişikliğini nasıl güvenle devreye alırım?	Yeni sertifikayı ekleyip politikayı güncelleyin, test ortamında doğrulayın, ardından deploy edin.
Kullanım	Şifrelenmesi gereken alanlar değiştiğinde ne yapmalıyım?	encPartList’teki kayıtları güncelleyin, yeni eleman adı ve namespace’i ekleyerek politikayı tekrar kaydedin.