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