> ## Documentation Index > Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt > Use this file to discover all available pages before exploring further. # 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?](/tr/concepts/temel-kavramlar/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 WS-Security Şifreleme Politikası ### 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](/tr/concepts/temel-kavramlar/dinamik-degiskenler) 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)](/tr/concepts/temel-kavramlar/politika-nedir#koşullar) | | **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?](/tr/concepts/temel-kavramlar/politika-nedir) sayfasındaki [Koşullar](/tr/concepts/temel-kavramlar/politika-nedir#koşullar) ve [Hata Mesajı Özelleştirme (Error Message Customization)](/tr/concepts/temel-kavramlar/politika-nedir#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](/tr/concepts/temel-kavramlar/hata-mesaji-yapilandirma) sayfasına bakın. ## Politikayı Silme Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için [Politika Yönetimi](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi) sayfasındaki [Akıştan Politika Kaldırma](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi#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](/tr/admin/secrets-management/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](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi) sayfasındaki [Politikayı API'ye Bağlama](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi#akisa-politika-ekleme) 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. |