WS-Security Güvenlik İmzalama

ipucu

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 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

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 İ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ı?
3. İ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.
4. 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.
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

• 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: 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: İ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 5: İ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 6: İ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 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 imzalanacak parça veya temel imza parametresi 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 İ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.