WS-Security Güvenlik İmza Doğrulama

SOAP mesajlarındaki WS-Security imzalarını doğrulayabilir ve isteği isteğe göre reddedebilirsiniz

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?

• SOAP zarflarındaki WS-Security Signature bloklarını doğrulayarak bütünlük ve kimlik doğrulaması sağlar.
• Yetkisiz sertifikalar veya bozulmuş imzalarla gelen çağrıları engelleyerek Canlı Ortam güvenliğini artırır.
• Anahtar yönetimi için merkezi KeyStore entegrasyonu ile imza doğrulama süreçlerini standartlaştırır.
• Gelişmiş doğrulama seçenekleri sayesinde farklı iş yükleri için özelleştirilebilir güvenlik seviyeleri 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 İmza Doğrulama 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 İmza Doğrulaması: SOAP mesajındaki Signature elementi seçilen KeyStore’daki açık anahtar sertifikası ile doğrulanır; isteğe bağlı olarak imza kaldırma ve mustUnderstand başlıkları denetlenir.
4. Karar Verme:
   • Eşleşme Var: İmza doğrulaması başarılı, mesaj işleme devam eder.
   • Eşleşme Yok: İmza doğrulaması başarısız, politika yapılandırmasındaki hata kodu ve mesaj döndürülür.
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

• KeyStore Doğrulaması: İmza doğrulama işlemleri için seçilen KeyStore kaynağındaki sertifikaları kullanır.
• Gelişmiş İmza Denetimi: Birden fazla dijital imza varyasyonunda derin doğrulama yapabilmek için ek kontroller sunar.
• SOAP MustUnderstand Desteği: mustUnderstand işaretli WS-Security başlıklarının zorunlu olarak işlenmesini garanti eder.
• 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

• İmza Kaldırma Opsiyonu: Doğrulama sonrası imza bloklarını mesajdan çıkararak arka uç servislerin sade içerik almasını sağlar.
• Case-Insensitive ID Kontrolü: SOAP imza referanslarındaki ID değerlerini harf duyarsız karşılaştırma modunda doğrular.
• Dereference İmza Yönetimi: Referanslı imza kaldırma senaryolarında SOAP gövdesinin yeniden çözümlenmesini 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ç
Sertifikalı SOAP Erişimi	Harici bankacılık entegrasyonu için imzalı SOAP çağrıları geliyor	Varsayılan KeyStore seçilir, Enhanced Signature Validation aktif edilir.	İmza doğrulanır, geçerli isteklere 200 döner, geçersiz imzada 403.
İmzasız İstek Engelleme	İmza taşımayan istemciler sistemi suistimal ediyor	MustUnderstand aktif, hata mesajı özelleştirilir.	İmzasız çağrılar 403 ile engellenir, loglarda sebep görünür.
Çoklu Sertifika Yönetimi	Aynı Endpoint için farklı sertifika sürümleri var	Policy kopyalanır, farklı KeyStore kayıtları atanır.	Her sürüm için doğru sertifika kullanılarak erişim sağlanır.
Performans Optimizasyonu	Arka uç servis imza bloklarını desteklemiyor	Remove Signature aktif edilir.	İmza doğrulandıktan sonra mesaj sadeleştirilir, servis uyum sorunu çözülür.
Legacy Uyum	Eski istemciler ID alanında büyük/küçük harf karıştırıyor	Enhanced Validation + Case-Insensitive ID aktif edilir.	Harf duyarsız karşılaştırma ile isteklere izin verilir.
Dereference Koruması	Mesajlarda referans çözümleme zorlukları yaşanıyor	Signature Removal for Dereferencing aktif edilir.	Gövdedeki referans işaretçileri düzgün çözülür.
Deneme Ortamı Sertifika Testi (opsiyonel)	Test ortamında yeni sertifikalar denenecek	Politika localize edilir, yeni KeyStore atanır.	Testte doğrulama sağlanır, hata mesajları kayıt altına alını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 İmza Doğrulama 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 İmza Doğrulama 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_SignValidation - 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: “Harici SOAP servisleri için WS-Security imza doğrulaması” - 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: KeyStore Seçimi	- Verification KeyStore alanından imza doğrulamada kullanılacak sertifikayı seçin. - Listede aktif projeye ait KeyStore kayıtları alfabetik sıralı gelir. - Seçim yapılmazsa istekler doğrulanamaz ve politika kaydedilemez.
Adım 5: Gelişmiş Doğrulama Seçenekleri	- Enable Enhanced Signature Validation kutucuğu ile ekstra WS-Security kontrollerini devreye alın. - Bu seçenek aktifken Allow Case Insensitive ID alanı görünen hale gelir ve ID karşılaştırmasını harf duyarsızlaştırır. - Dereference hatalarını önlemek için Enable Signature Removal for Dereferencing seçeneğini kullanın.
Adım 6: SOAP Davranışı Parametreleri	- Must Understand seçeneği zorunlu WS-Security başlıklarını denetler. - Remove Signature ile doğrulama sonrasında Signature elementini mesajdan kaldırabilirsiniz. - Bu seçenek arka uç servislerin sadece iş verisine odaklanmasını sağlar.
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 KeyStore seçimi 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
Dinamik KeyStore Tazeleme	- KeyStore servisinde yapılan güncellemeler listeye otomatik yansır. - Yeni sertifikayı ekledikten sonra sayfayı yenilemeye gerek yoktur. - Hızlı geçişle bakım sürelerini kısaltır.
Global-Local Eşleştirme Desteği	- Global politikayı local kopyaya dönüştürerek test amaçlı özelleştirin. - Local kopyada farklı KeyStore veya hata mesajları deneyin. - Gerektiğinde tekrar global hâle getirin.
Hata Mesajı Senaryoları	- Farklı hata kodları tanımlayarak istemcilere yönlendirici geri bildirim verin. - JSON formatında detaylı hata alanları ekleyin. - Başarılı doğrulama sonrası loglama seviyesini optimize edin.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
KeyStore Yönetimi	Kötü: Tek sertifika ile tüm ortamları yönetmek. İyi: Ortam bazlı KeyStore ayırmak. En İyi: Sertifika yenilemelerinde export/import ile versiyonlama yapmak.
Hata Mesajları	Kötü: Varsayılan mesajı bırakmak. İyi: Kısa özel mesaj eklemek. En İyi: Hata kodu, izleme ID’si ve destek ileti bilgisi içeren JSON döndürmek.
Koşul Kullanımı	Kötü: Tüm API Proxy (API Vekil Sunucusu) için koşulsuz uygulamak. İyi: Sadece SOAP endpoint’lerine koşul tanımlamak. En İyi: Endpoint, Header ve method kombinasyonlarıyla hassas koşullar oluşturmak.
Gelişmiş Doğrulama	Kötü: Eski istemcilerde gereksiz açıkları kapatmadan bırakmak. İyi: Enhanced validation’ı test ederek açmak. En İyi: Harf duyarsız ID ve dereference kaldırma seçeneklerini senaryo bazlı aktifleştirmek.
İmza Kaldırma	Kötü: Arka uç uyumluluğunu kontrol etmeden Remove Signature’ı etkinleştirmek. İyi: QA ortamında fonksiyonel test yapmak. En İyi: Performans ve güvenlik testlerini birlikte yürütmek.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Sertifika Güvenliği	KeyStore erişimini sadece yetkili yöneticilere verin, şifreleri Config Vault’ta saklayın.
İmza Doğrulama	Enhanced validation açıldığında ek imza doğrulama log’larını izleyin, hatalı imzaları hızla ayıklayın.
Must Understand Yönetimi	mustUnderstand devre dışı ise SOAP uyumluluğu bozulabilir; kapatmadan önce arka uç destek durumunu doğrulayın.
Loglama	403 dönen isteklerde Header ve Endpoint bilgilerini maskelenmiş şekilde loglayın.
Atağa Kapı Açmama	Dereference kaldırma özelliğini bilinmeyen istemcilerde kapalı tutarak SOAP içerik enjeksiyon risklerini azaltın.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Yanlış KeyStore Seçimi	Neden kaçınılmalı: Yanlış sertifika ile tüm isteklere 403 dönebilir. Alternatif: Ortam bazlı doğrulama kontrol listesi oluşturun.
Koşulsuz Uygulama	Neden kaçınılmalı: JSON/REST endpoint’leri gereksiz yere başarısız olabilir. Alternatif: Sadece SOAP path’leri ile sınırlı koşullar tanımlayın.
Hata Mesajı Boş Bırakma	Neden kaçınılmalı: İstemci tarafı kök sebebi anlayamaz, destek yükü artar. Alternatif: JSON hata mesajına destek iletişim bilgisi ekleyin.
Test Etmeden Remove Signature	Neden kaçınılmalı: Bazı arka uç servisleri imzayı bekler. Alternatif: Önce test ortamında doğrulayın, sonra Canlı Ortam’a alın.

​

Performans İpuçları

Kriter	Öneri / Etki
KeyStore Erişim Süresi	Öneri: KeyStore servisinde gereksiz kayıtları temizleyin. Etki: İmza doğrulama süresi kısalır.
Enhanced Validation	Öneri: Yüksek trafikli ortamlarda sadece gerekli olduğunda açın. Etki: CPU kullanımı dengelenir.
Remove Signature	Öneri: Arka uç JSON dönüşümünde gerekli ise aktif edin. Etki: SOAP → REST dönüştürücülerde latency azaltır.
Koşul Filtreleri	Öneri: Endpoint ve Header bazlı koşullarla gereksiz doğrulamaları engelleyin. Etki: Gateway yükü hafifler.
Log Düzeyi	Öneri: Başarılı doğrulamalarda log seviyesini INFO yerine DEBUG tutmayın. Etki: Disk kullanımı ve IO maliyeti azalır.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	WS Güvenlik İmza Doğrulama politikası hangi API türlerinde çalışır?	SOAP tabanlı ve WS-Security imzalı SOAP mesajlarını hedefler; REST çağrıları için koşul ekleyerek devre dışı bırakabilirsiniz.
Genel	KeyStore seçmeden politika kaydı yapılabilir mi?	Hayır, doğrulama için en az bir KeyStore seçimi zorunludur, aksi hâlde politika kaydedilemez.
Teknik	Enhanced Signature Validation ne sağlar?	İmza referans çözümleme, canonicalization ve ID eşleşmelerinde ek kontroller yaparak imza spoofing saldırılarını önler.
Teknik	Case-Insensitive ID hangi senaryolarda kullanılmalı?	Legacy istemcilerde ID alanlarının karışık harf kullanımı varsa aktifleştirin, modern istemcilerde kapalı tutun.
Kullanım	Remove Signature seçeneği arka uç servisi etkiler mi?	İmza doğrulandıktan sonra SOAP mesajından kaldırılır; arka uç servisin imza beklemediği durumlarda kullanılmalıdır.
Kullanım	Politikayı API Proxy (API Vekil Sunucusu) bazında nasıl uygularım?	API ayarlarında Policies sekmesinden global politikayı bağlayabilir veya local kopya oluşturup özelleştirebilirsiniz.