Genel Bakış
Amacı Nedir?
- SOAP tabanlı isteklerde imzalanması gereken XML düğümlerini belirleyerek iletim bütünlüğünü garanti altına almak.
- Seçilen API Proxy (API Vekil Sunucusu) ve Policy akışlarında merkezi imza yönetimi sağlayarak anahtar kullanımını standartlaştırmak.
- WS-Security standartlarına uyumlu imza algoritmalarını ve canonicalization seçeneklerini tek merkezden yapılandırmak.
- WSI BSP uyumluluk gereksinimi olan entegrasyonlarda, uyum kontrollerini katmanlı olarak devreye almak.
Ç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 İmzalama 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ı?
- İmza Konfigürasyonu Doğrulama: Politika, sigKeyStoreId, sigKeyIdType ve gerektiğinde sigCustomKeyIdentifier alanlarının eksiksiz tanımlandığını, seçilen algoritmaların keystore ile uyumlu olduğunu ve imzalanacak parçaların listelendiğini doğrular.
- Karar Verme:
- Eşleşme Var: Belirlenen XML parçaları seçilen algoritmalar ile imzalanır, mustUnderstand bayrağı gerekiyorsa SOAP header’a işlenir ve hedefe iletilir.
- Eşleşme Yok: İstek imza uygulanmadan veya hata mesajı tetiklenmeden bir sonraki Policy kontrolüne yönlendirilir.
- 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
- Anahtar Deposu Entegrasyonu: SigKeyStoreId alanı ile kurumun merkezi KeyStore servisindeki sertifikalar kullanılarak imzalama yapılır; kayıtlı depo listesi otomatik yüklenir.
- Esnek Key Identifier Seçenekleri: X509, Subject Key Identifier veya Custom Key Info gibi WS-Security anahtar tanımlayıcıları seçilerek farklı SOAP tüketicilerine uyum sağlanır.
- İmzalanacak Parçaları Yönetme: SigPartList aracılığıyla Body, Header veya özel elemanlar ELEMENT/CONTENT bazında işaretlenerek imza kapsamı özelleştirilir.
- 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
- Advanced Algorithm Tuning: RSA, DSA, ECDSA veya HMAC tabanlı imza/digest algoritmalarından seçim yaparak performans ile uyumluluk arasında denge kurma.
- WSI BSP Uygunluk Modu: SigWsiBSPCompliant bayrağı ile Basic Security Profile kontrolleri devreye alınarak dış sistemlerin uyumluluk testleri kolaylaştırılır.
- Sertifika Kullanım Optimizasyonu: SigUseSingleCert seçeneği ile tek sertifika veya zincir bazlı imza stratejileri yönetilir; karmaşık keystore senaryoları sadeleştirilir.
- 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ç |
|---|---|---|---|
| Kurumsal SOAP SLA | B2B SOAP servisleri imzasız bırakılıyor | SigKeyStoreId seçilerek şirket sertifikası, RSA_SHA256 imza ve SHA256 digest ile aktif edilir. | Karşı taraf imzayı doğrular, mesaj bütünlüğü sağlanır. |
| Hybrid Key Identifier | Farklı tüketiciler farklı key identifier bekliyor | Global politika Custom Key Info alanını doldurarak çoğaltılır. | Her tüketici için doğru Subject veya Custom referans döner. |
| XML Parça Koruması | Sadece ödeme alanları imzalanmalı | SigPartList’e payment öğesi (ELEMENT) eklenir. | İlgili element imzalanır, diğer alanlar serbest kalır. |
| WSI BSP Denetimi | Sertifikasyon testleri BSP uyumu istiyor | SigWsiBSPCompliant aktif edilir, canonicalization C14N_EXCL seçilir. | Test araçları BSP ihlali raporlamaz. |
| Tek Sertifika Kısıtı | Keystore tek sertifika içeriyor | SigUseSingleCert işaretlenir, key identifier X509 seçilir. | Policy sertifika aramasını basitleştirir, hata düşer. |
| Must Understand Zorunluluğu | Middleware mustUnderstand arıyor | MustUnderstand bayrağı aktif edilir. | SOAP header WSU:MustUnderstand=1 içerir, aracı hata vermez. |
| İç İletişim Senaryosu (opsiyonel) | İç sistemler düşük güvenlik ister | Passive modda bırakılır, koşulla sadece prod isteklere uygulanır. | Test ortamı imzasız kalır, Canlı ortam korunur. |
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 İmzalama 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 İmzalama Politikası 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_Sign- 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: “SAP entegrasyonlarında outbound imza sağlar.” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: İmza Anahtar Yapılandırması | - Signature KeyStore listesinden kullanılacak sertifika deposunu seçin. - Key Identifier Type ile imza tespit yöntemi (X509, Subject Key Identifier, Custom Key Info vb.) belirlenir. - Custom Key Info seçildiğinde sigCustomKeyIdentifier ve sigCustomKeyIdentifierValueType alanlarını doldurun. |
| Adım 4: İmza Algoritmaları ve Uyum Seçimleri | - sigSigAlgorithm, sigC14n, sigDigAlgorithm alanlarından uygun algoritmaları seçin.- sigUseSingleCert ve sigWsiBSPCompliant bayraklarıyla sertifika kullanım stratejisini ve BSP uyumluluğunu belirleyin.- mustUnderstand seçeneği SOAP header düzeyinde zorunluluk oluşturur. |
| Adım 5: İmzalanacak SOAP Parçalarını Tanımlama | - Add Signature Part butonuyla Body, Header veya özel elementleri listeye ekleyin.- Her parça için ad, namespace ve encodeType (ELEMENT/CONTENT) seçerek XML kapsamını kesinleştirin. - Gerekirse mevcut kayıtları düzenleyin veya silin. |
| 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 imzalanacak parça veya temel imza parametresi 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 İmza Algoritması Profilleme | - Ortak imza gereksinimleri için ön tanımlı RSA, DSA, ECDSA seçenekleri arasından seçim yapılır. - Farklı tüketiciler için birden fazla politika türetilerek algoritmalar ayrıştırılır. - Performans takibiyle uygun algoritma kombinasyonu korunur. |
| Özel Key Identifier Uygulamaları | - Custom Key Info seçildiğinde identifier ve valueType alanları doldurulur. - SOAP tüketicisinin beklediği referans formatına göre değerler belirlenir. - Değişiklikler export edilerek diğer ortamlara taşınır. |
| İmzalanacak Parça Yönetim Otomasyonu | - SigPartList ile XML parçaları kaydedilir. - EncodeType seçimiyle bütün öğe veya yalnızca içerik imzalanır. - Menü üzerinden parçalar düzenlenir veya silinir, sürüm kontrolünde izlenir. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Keystore Yönetimi | Kötü: Belirsiz keystore isimleri kullanmak. İyi: Ortam bazlı ön ekler eklemek ( Prod_KS).En İyi: Keystore’ları isim, sertifika tipi ve süresiyle etiketlemek. |
| Algoritma Seçimi | Kötü: Varsayılan SHA1 algoritmasına bağlı kalmak. İyi: SHA256 kullanmak. En İyi: Karşı tarafın desteğine göre SHA384/SHA512 protonu seçmek. |
| Signature Parts Yönetimi | Kötü: Tüm mesajı imzalamak. İyi: Kritik alanları seçmek. En İyi: EncodeType ve namespace bilgilerini dokümante ederek yönetmek. |
| Must Understand Kullanımı | Kötü: Her entegrasyonda zorunlu kılmak. İyi: Orta katman gereksinimlerine göre seçmek. En İyi: Sadece SOAP aracı tarafı zorunlu tutuyorsa aktif etmek. |
| BSP Uyumluluk Kontrolü | Kötü: Tüm senaryolarda kapalı bırakmak. İyi: Dış sistem talep ettiğinde açmak. En İyi: Uyum testleri sonrası politika kopyalayarak profil bazlı yönetmek. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Sertifika Döngüsü | Sertifika süresini takip edin, süresi dolmadan keystore güncelleyip policy’yi yeniden deploy edin. |
| Anahtar Paylaşımı | Keystore erişimlerini ayrıştırın, sadece yetkili DevOps kullanıcılarına izin verin. |
| Custom Identifier Kullanımı | Custom Key Info değerlerini gizlilik gerektiren ortamlarda loglama; maskelenmiş tutun. |
| Algoritma Güncellemeleri | Güvenlik duyurularını izleyin, zayıf sayılan RSA_SHA1 gibi algoritmaları devreden çıkarın. |
| Hata Mesajı Yönetimi | Özelleştirilmiş hata mesajlarında iç sistem detaylarını paylaşmayın, genel ifadeler kullanın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Eksik Signature Part Tanımı | Neden kaçınılmalı: Kritik element imzalanmazsa mesaj manipüle edilebilir. Alternatif: İmzalanması gereken her element için SigPartList oluşturun. |
| Uyumsuz Algoritma Seçimi | Neden kaçınılmalı: Karşı sistem desteklemediğinde hata döner. Alternatif: Tüketici dokümantasyonunu inceleyip desteklenen algoritmaları seçin. |
| Keystore Erişim Hatası | Neden kaçınılmalı: Yanlış keystore ID politika çalışmasını engeller. Alternatif: Keystore listesi güncellendiğinde politikayı tekrar kaydedin. |
| BSP Uyumu Zorunlu Tutmak | Neden kaçınılmalı: Bazı sistemler WSI BSP kısıtlarıyla uyumsuz olabilir. Alternatif: Gereksinimi olmayan entegrasyonlarda bayrağı pasif bırakın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Algoritma Karmaşıklığı | Öneri: SHA256 ve RSA_SHA256 çoğu senaryo için yeterlidir. Etki: CPU tüketimi dengelenir, gecikme artmaz. |
| İmza Parça Sayısı | Öneri: Sadece zorunlu elementleri imzalayın. Etki: XML canonicalization süresi kısalır. |
| Keystore Erişim Süresi | Öneri: Keystore servisinin aynı veri merkezinde olması sağlanmalı. Etki: İmza oluşturma gecikmesi düşer. |
| Policy Cache Kullanımı | Öneri: Sık kullanılan politikaları API katmanında cache’leyin. Etki: Policy yükleme süreleri azaltılır. |
| Hata Mesajı İşleme | Öneri: Yoğun trafikte standart hata mesajı kullanın. Etki: JSON oluşturma maliyeti düşer. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | WS Güvenlik İmzalama Politikası ne zaman kullanılmalı? | SOAP tabanlı servislerde mesaj bütünlüğü veya kimlik doğrulama talebi varsa bu politika devreye alınmalıdır. |
| Genel | Politikayı pasife almak imzayı tamamen kapatır mı? | Evet, politikayı pasife aldığınızda imza uygulanmaz ancak yapılandırma korunur. |
| Teknik | Custom Key Info seçtiğimde hangi alanlar zorunlu? | sigCustomKeyIdentifier ve sigCustomKeyIdentifierValueType alanları doldurulmalıdır; aksi halde politika hataya düşer. |
| Teknik | Birden fazla imza algoritması seçilebilir mi? | Hayır, her politika için tek imza, tek canonicalization ve tek digest algoritması seçilir; farklı profiller için politika kopyalayın. |
| Kullanım | Signature parts listesine namespace yazmak zorunlu mu? | Hayır, ancak benzer isimli öğeler varsa karışmaması için namespace eklemeniz önerilir. |
| Kullanım | Must Understand bayrağı uygulamayı nasıl etkiler? | SOAP header’daki security bloğu zorunlu kılınır; ara katman bu bloğu anlamazsa fault dönebilir. |