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
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- 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ı?
- 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.
- 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.
- 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:
mustUnderstandiş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: 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 4: 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 5: 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 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 KeyStore seçimi 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 |
|---|---|
| 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. |