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
- İstek Gelişi: WS-Security Şifreleme politikası, API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- 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ı?
- 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.
- 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.
- 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: Ş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 4: 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 5: Ş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 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 şifrelenmiş parça 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 |
|---|---|
| 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. |