WS-Security (Gelen Mesaj)

SOAP hedefine giden iletilere WS-Security katmanı ekleyerek kimlik doğrulama, imzalama ve şifrelemeyi otomatik uygulayabilirsiniz

Son Güncelleme: 11 Kasım 2025
Hedef Kitle: Sistem Yöneticileri, Backend Geliştiriciler, DevOps Mühendisleri

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.

Alan	Değer
Politika Adı	WS Security To Target Politikası
Özet	SOAP hedefine giden iletilere WS-Security katmanı ekleyerek kimlik doğrulama, imzalama ve şifrelemeyi otomatik uygular.
Kategori	Güvenlik ve Erişim Kontrolü
Dönüş Durum Kodları	Aşağıdaki tabloda detaylı bilgi verilmiştir.

​

Dönüş Durum Kodları

Hata Kodu	Hata Mesajı	HTTP Durum Kodu
ERR-060	WS-Security policy failed! Error message is:	500

​

Genel Bakış

​

Amacı Nedir?

• SOAP hedefine güvenlik katmanı ekleme: Hedef servise giden mesajlara WS-Security standartlarına uygun güvenlik bileşenlerini ekleyerek entegrasyon gereksinimlerini karşılar.
• Kimlik doğrulama ve yetkilendirme zorlaması: UsernameToken veya imza doğrulaması isteyen servisler için gerekli kimlik bilgilerini ve dijital imzayı mesajlara dahil eder.
• Veri bütünlüğü ve gizliliği sağlama: Şifreleme ve imzalama sırasını kontrol ederek aktarım sırasında mesajın bütünlüğünü ve gizliliğini korur.
• Uyumluluk ve denetlenebilirlik: Zaman damgası ve Must Understand ayarlarıyla servis sağlayıcıların uyumluluk kontrollerini geçmeyi kolaylaştırır.

​

Ç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 Security To Target 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. Güvenlik Bileşenlerinin Derlenmesi: Politika tanımındaki WS-Security giriş sırası (Timestamp, UsernameToken, Encryption, Signature) okunur; seçilen her bir bileşen için gerekli anahtarlar, parolalar ve algoritmalar doğrulanır ve SOAP zarfına eklenmeye hazırlanır.
4. Karar Verme:
   • Eşleşme Var: Tüm seçili bileşenlerin zorunlu alanları doluysa ve keystore erişimi sağlanıyorsa SOAP mesajı güncellenir, hedef Endpoint’e güvenli şekilde yönlendirilir.
   • Eşleşme Yok: Eksik sertifika, kullanıcı bilgisi veya algoritma seçimi tespit edilirse politika yürütmesi durdurulur ve isteğe hata dönüşü hazırlanı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

• Çoklu WS-Security Bileşeni Yönetimi: Timestamp, UsernameToken, Encryption ve Signature öğelerini tek politikada birleştirerek hedef WS-Security gereksinimlerini karşılar.
• Dinamik Operasyon Sırası: Sürükle-bırak ile güvenlik bileşenlerinin çalıştırılma sırasını belirleyerek servis sağlayıcının beklediği düzenle eşleşme sağlar.
• Parça Bazlı Şifreleme/İmzalama: SOAP mesajının belirli element veya içerik kısımlarını seçerek parça bazlı şifreleme ve imza tanımlarını destekler.
• 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

• Keystore Entegrasyonu: Şifreleme ve imza keystore’larını Apinizer Secret Manager üzerinden seçerek merkezi sertifika yönetimi sağlar.
• Algoritma Esnekliği: Symmetric, Key Encryption, Signature, Canonicalization ve Digest algoritmalarını standart listelerden seçme imkanı sunar.
• Özel Anahtar Tanımlayıcılar: Custom Key Info veya Embedded Key Info gibi özel SOAP başlık alanlarıyla hedef servislerin özel gereksinimlerini karşılar.
• 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ç
Banka Entegrasyonu	Hedef SOAP servis UsernameToken zorunlu kılıyor.	UsernameToken bileşeni eklenir, kullanıcı ve parola girilir, PasswordDigest seçilir.	Hedef servis kimlik doğrulamayı kabul eder, işlem onaylanır.
Sigorta Web Servisi	Servis hem imza hem şifreleme talep ediyor.	Encryption ve Signature bileşenleri eklenir, ayrı keystore’lar atanır.	Mesaj imzalanır ve şifrelenir, servis güvenlik kontrollerini geçer.
Zaman Kısıtlı Servis	Servis belirli TTL içinde gelen istekleri kabul ediyor.	Timestamp bileşeni eklenir, tsTimeToLive değeri 300 sn yapılır.	Mesaj, hedef sistemin beklediği zaman damgasıyla teslim edilir.
Erişim İzleme	Hedef servis MustUnderstand flag kontrol ediyor.	Must Understand işaretlenir, tüm bileşenler için flag true gönderilir.	Servis mesajı işler, uyumluluk ihlali oluşmaz.
Bölgesel Anonimleştirme	Bazı XML alanları şifrelenmeli.	Encryption part listesine ilgili element namespace’leri eklenir.	Sadece ilgili alanlar şifrelenir, diğer kısımlar okunabilir kalır.
İç Sistemler için HMAC	Kurum içi servis HMAC imzası bekliyor.	Signature algoritması olarak HMAC_SHA256 seçilir, tek sertifika kullanımı devre dışı bırakılır.	Mesaj HMAC ile imzalanır, hedef doğrulamayı başarıyla tamamlar.
Test Ortamında Basit Kimlik (opsiyonel)	Test sisteminde sadece kullanıcı bilgisi gerekli.	Sadece UsernameToken aktif edilir, encryption ve signature pasif bırakılır.	Konfigürasyon hızlıca test edilir, gereksiz kripto yükü oluşmaz.

​

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 To Target 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 Security To Target 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_WSST - 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: “Hedef SOAP servise WS-Security ekler.” - 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: WS-Security Girişlerini Tanımlama	- Must Understand bayrağını gerekliyse etkinleştirin. - Add Entry üzerinden gerekli modülleri (Timestamp, UsernameToken, Encryption, Signature) seçin. - Giriş sırasını sürükle-bırak ile talep edilen iş akışına göre düzenleyin.
Adım 5: Şifreleme Parametrelerini Ayarlama	- Encryption bölümünde kullanılacak keystore’u seçin veya yeni keystore açın. - Anahtar tanımlayıcı ve simetrik/anahtar şifreleme algoritmalarını hedef servisin desteklediği seçeneklere göre belirleyin. - Şifrelenmesi gereken XML elemanlarını Encryption Parts tablosuna ekleyin.
Adım 6: İmza Parametrelerini Ayarlama	- Signature bölümünde imza keystore’unu seçin. - Signature, Canonicalization ve Digest algoritmalarını belirleyin. - Custom Key Info gereken senaryolarda kimlik bilgisi alanlarını doldurun. - İmzalanacak alanları Signature Parts tablosuna ekleyin.
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 WS-Security bileşeni seçili. 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 bölümüne bakabilirsiniz.

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 Akışa Politika Ekleme bölümüne bakabilirsiniz.

​

İleri Düzey Özellikler

Özellik	Açıklama ve Adımlar
Anahtar Tanımlayıcı Modları	- Hedef servis talebine göre Binary Token, Issuer Serial veya Custom Key Info seçin. - Custom seçildiğinde tanımlayıcı değerlerini zorunlu girin. - Embedded Key Info için gömülü anahtar adını belirtin.
Parça Bazlı Güvenlik	- Şifreleme veya imza için XML elementlerini tabloya ekleyin. - Content veya Element seçimiyle sadece içerik ya da tüm düğümü koruyun. - Namespace eşleşmesini doğrulamak için test çağrıları yapın.
Çoklu Keystore Yönetimi	- Entegrasyonlarda farklı sertifikalar gerekiyorsa iki ayrı keystore tanımlayın. - Gerektiğinde yeni keystore açmak için + butonunu kullanın. - Secret Manager güncellemeleri otomatik olarak listeye yansır.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Keystore Yönetimi	Kötü: Keystore parolasını paylaşılan dökümanda tutmak. İyi: Parolayı gizli kasada saklamak. En İyi: Keystore’u Apinizer Secret Manager ile yönetip erişimi rol bazlı sınırlandırmak.
Algoritma Seçimi	Kötü: Varsayılan SHA1 imzasını her ortamda kullanmak. İyi: Servisin desteklediği en güçlü algoritmayı seçmek. En İyi: RSA_SHA256 veya AES_256_CBC gibi güncel algoritmalarla periyodik güvenlik incelemesi yapmak.
Bileşen Sıralaması	Kötü: Rastgele sıralama bırakmak. İyi: Servis dökümantasyonundaki sıraya uymak. En İyi: Güvenlik testi sonuçlarına göre sıralamayı doğrulamak ve değişikliklerde regresyon testi yapmak.
Politika İsimlendirmesi	Kötü: Genel isimler (ör. “policy1”). İyi: Ortam ve kapsam eklemek (ör. “Prod_WSST”). En İyi: {Ortam}_{Servis}_{Bileşenler} formatı kullanıp yönetişim raporlarıyla eşleştirmek.
UsernameToken Yönetimi	Kötü: Parolaları manuel güncellemek. İyi: Dönemsel parola rotasyonu planlamak. En İyi: Parolayı harici gizli kasadan çekip Apinizer değişkenleriyle otomatik güncellemek.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Sertifika Yaşam Döngüsü	Keystore sertifikalarının bitiş tarihlerini izleyin, expiry uyarılarını göz ardı etmeyin.
Nonce ve Created Kullanımı	Replay saldırılarını önlemek için UsernameToken’da Nonce ve Created alanlarını aktif bırakın.
Must Understand Bayrağı	Hedef servis WS-Security taglerinin zorunlu olduğunu belirtiyorsa flag’i mutlaka işaretleyin.
Digest Algoritması Güncelliği	SHA1 veya MD5 gibi kırılgan algoritmalar yerine SHA256+ seçeneklerini tercih edin.
Hata Mesajı Maskeleme	Özelleştirilmiş hata mesajlarında hassas detayları paylaşmayın, genel hata kodları kullanın.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Eksik Keystore Ataması	Neden kaçınılmalı: Encryption/Signature etkinse keystore olmadan politika hata verir. Alternatif: Önce Secret Manager’da ilgili keystore’u tanımlayın ve seçin.
Yanlış Namespace Tanımı	Neden kaçınılmalı: Hedef element bulunamaz, şifreleme/imza atlanır. Alternatif: WSDL veya örnek cevap üzerinden doğru namespace’i kopyalayın.
Uygunsuz Sıralama	Neden kaçınılmalı: Bazı servisler sırayı doğrular, yanlış sıra reddedilir. Alternatif: Sıralamayı dokümantasyonla eşleştirin, test çağrılarıyla kontrol edin.
Sabit Parolalar	Neden kaçınılmalı: Parola sızıntısı tüm entegrasyonu riske atar. Alternatif: Parolaları periyodik olarak değiştirin ve gizli kasada tutun.

​

Performans İpuçları

Kriter	Öneri / Etki
Kriptografik Yük	Öneri: Sadece gerekli bileşenleri aktif edin. Etki: Gereksiz şifreleme kaldırılarak gecikme azalır.
Keystore Boyutu	Öneri: Keystore’u sadece gerekli sertifikalarla sınırlayın. Etki: Bellek kullanımı düşer, yükleme süresi kısalır.
Digest Algoritması	Öneri: SHA256 çoğu senaryoda optimumdur. Etki: Güvenlik/gösterim dengesini korurken CPU maliyetini dengeler.
Parça Sayısı	Öneri: Şifrelenen/imzalanan elementleri minimum seviyede tutun. Etki: Mesaj boyutu küçülür, hedef servis işleme süresi kısalır.
Cache Kullanımı	Öneri: Keystore erişim sonuçlarını Cache’de saklayın. Etki: Sertifika okuma süresi azalır, yanıt süresi stabil kalır.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	WS Security To Target politikası hangi durumlarda gerekli?	Hedef SOAP servisin WS-Security (Timestamp, UsernameToken, Encryption veya Signature) zorunlu kıldığı tüm senaryolarda kullanılmalıdır.
Genel	Politikayı pasifleştirirsem yapılandırma kaybolur mu?	Hayır, pasif modda parametreler saklanır; yeniden aktifleştirildiğinde aynı şekilde uygulanır.
Teknik	Keystore’u nasıl ekleyebilirim?	Secret Manager’da JKS formatında keystore oluşturun; politika ekranındaki + butonuyla listeye ekleyip seçin.
Teknik	Custom Key Info ne zaman kullanılmalı?	Hedef servis imzada özel bir anahtar tanımlayıcı beklediğinde Custom Key Info seçilmeli ve identifier alanları doldurulmalıdır.
Kullanım	UsernameToken parolasını nasıl gizleyebilirim?	Parolayı Apinizer Secret Manager değişkeniyle saklayıp politikada ilgili değişkeni referans gösterin.
Kullanım	API Proxy (API Vekil Sunucusu) ile eşleştirme sonrası deploy gerekir mi?	Global politikalar için evet; değişiklikler canlıya aktarılmadan önce deploy işlemi yapılmalıdır.