WS-Security Username Token

SOAP isteklerine yapılandırılabilir WS-Security UsernameToken ekleyerek kimlik doğrulaması uygulayabilirsiniz

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?

• Kullanıcı adı ve parola tabanlı WS-Security UsernameToken oluşturup SOAP mesajlarına ekleyerek servis sağlayıcıların beklediği kimlik doğrulamayı sağlar.
• Şifre türü, nonce ve created damgaları gibi güvenlik bayraklarını yöneterek hedef servisin parola politikalarına uyum değişkenliğini temin eder.
• MustUnderstand bayrağı üzerinden tüketilen servisin başlık denetimi gereksinimlerini karşılayarak entegrasyon hatalarını azaltır.
• API Proxy (API Vekil Sunucusu) çağrıları için konfigüre edilebilir hata mesajı ve durum kodu yönetimi sunarak gözlenebilirliği güçlendirir.

​

Ç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üvenliği Kullanıcı Adı 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. UsernameToken Üretimi: Politika yapılandırmasındaki kullanıcı adı, parola ve parola tipi kullanılarak WS-Security UsernameToken oluşturulur; isteğe bağlı olarak nonce ve created alanları eklenir.
4. Karar Verme:
   • Eşleşme Var: UsernameToken SOAP zarfının Security başlığına eklenir ve istek hedef Endpoint’e yönlendirilir.
   • Eşleşme Yok: Politika uygulanmaz; istek mevcut header içerikleriyle iletilir.
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

• UsernameToken Enjeksiyonu: Yapılandırılan kullanıcı adı ve parola ile WS-Security UsernameToken üretir ve SOAP mesajına ekler.
• Parola Tipi Yönetimi: PasswordText veya PasswordDigest seçenekleriyle hedef servis beklentisine uygun şifreleme seviyesini sağlar.
• Kimlik Doğrulama Zenginleştirmesi: Nonce ve Created alanlarını ekleyerek tekrar saldırılarına karşı ek güvenlik katmanı oluşturur.
• 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

• MustUnderstand Bayrağı Yönetimi: WS-Security başlığına mustUnderstand özniteliği ekleyerek hedef servislerin zorunlu denetimlerini tetikler.
• Token Oluşturulma Kontrolü: Created damgasının eklenmesi sayesinde zaman damgalı doğrulama yapan servislerle uyum sağlar.
• Nonce Üretimi: Rastgele nonce üretimi ile PasswordDigest senaryolarında tekrar saldırısına karşı güvenliği artırır.
• 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ç
Eski SOAP Servisleri	Hedef servis yalnızca WS-Security UsernameToken kabul ediyor.	PasswordText seçilerek sabit kullanıcı adı/parola girilir.	İstekler başarıyla kimlik doğrulanır, 200 OK döner.
Bankacılık Entegrasyonu	Servis PasswordDigest ve nonce istiyor.	PasswordDigest seçilir, Nonce ve Created işaretlenir.	Servis tekrar saldırı korumasını doğrular, güvenli entegrasyon sağlanır.
Partner API Farklılığı	Partner ortamlarında farklı kullanıcı bilgileri kullanılıyor.	Her ortam için ayrı politika kopyalanır, koşullar ile ortam bazlı uygulanır.	Yanlış kimlik bilgisi kaynaklı hata oranı düşer.
Test Ortamı Simülasyonu	Canlı bilgiler paylaşılmadan test yapılmak isteniyor.	Geliştirme koşulu ile sahte kullanıcı seti atanır.	Test istekleri izole kullanıcı ile çalışır, canlı ortam etkilenmez.
Global Politika Yönetimi	Birden fazla API aynı kimlik bilgilerini kullanıyor.	Politika global olarak tanımlanır, ilgili API Proxy’lere bağlanır.	Tek noktadan yönetim sağlanır, değişiklikler otomatik yayılır.
Hata Mesajı Özelleştirme	Servis, özel hata kodu bekliyor.	Error Message Customization bölümünde JSON mesaj güncellenir.	Hedef sistem anlaşılır hata mesajı alır, destek ekibi tanılama süresi kısalır.
DevOps Otomasyonu (opsiyonel)	CI/CD pipeline’da politika versiyonlarını taşımak gerekiyor.	Export/Import ile zip paketleri oluşturulup pipeline’da deploy edilir.	Ortamlar arası geçişler izlenebilir hale gelir.

​

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üvenliği Kullanıcı Adı 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üvenliği Kullanıcı Adı 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_WSUserToken - 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: “BankCore SOAP servisi için WS Security UsernameToken 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: UsernameToken Parametreleri	- Username: SOAP başlığında kullanılacak kullanıcı adını girin. - Password: Maskelenmiş alana parolayı yazın. - Password Type: PasswordText veya PasswordDigest seçin; digest seçildiğinde parola otomatik olarak nonce ve zaman değeriyle hashlenir. Parola değerleri hassastır; erişim yetkilerini ihtiyaç kadar sınırlayın.
Adım 5: Must Understand ve Güvenlik Bayrakları	- Must Understand: Servisin WS-Security başlığını zorunlu tutmasını istiyorsanız işaretleyin. - Password Decryption: Sistem tarafından otomatik yönetilir, şifrenin çözülmesine izin vermez. - Bu seçenekler hedef SOAP servis uyumluluğunu sağlar.
Adım 6: Nonce ve Created Ayarları	- Nonce: Tekrarlanan saldırılara karşı rastgele Nonce eklemek için işaretleyin. - Created: UsernameToken içine oluşturulma tarihini ekleyin. - Digest kullanıyorsanız her ikisini de aktif tutmanız önerilir.
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 UsernameToken parametresi tanımlı. 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
Çoklu Ortam Kimlik Bilgileri Yönetimi	- Ortama göre farklı kullanıcı/parola setleri oluşturun. - Koşulları ortam başlığına bağlayın. - Export/Import ile ortamlar arasında senkron tutun.
Token Sürekliliği İzleme	- Error Message Customization üzerinden hata kodlarını log formatına göre düzenleyin. - Monitoring araçlarıyla korelasyon ID ekleyin. - Başarısız token üretimlerini merkezi olarak raporlayın.
Policy Group Otomasyonu	- Aynı UsernameToken’i kullanan API’leri Policy Group ile gruplayın. - Policy Group üzerinden toplu deploy gerçekleştirin. - Kullanım raporlarını izle, gereksiz kopyaları tespit et.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Kimlik Bilgisi Yönetimi	Kötü: Ortak kullanıcıyı tüm servisler için kullanmak. İyi: Servis bazlı kullanıcılar tanımlamak. En İyi: RBAC’e göre ayrı kullanıcı ve parola kasası entegrasyonu kullanmak.
Parola Güvenliği	Kötü: PasswordText seçeneğini varsayılan bırakmak. İyi: PasswordDigest kullanmak. En İyi: Parola rotasyonunu otomatikleştiren gizli yönetim servisi bağlamak.
Koşul Tasarımı	Kötü: Politikanın tüm isteklerde çalışmasına izin vermek. İyi: Endpoint bazlı koşullar tanımlamak. En İyi: Ortam, endpoint ve header kombinasyonlarına göre koşul matrisi oluşturmak.
Hata Yönetimi	Kötü: Varsayılan hata mesajını değiştirmemek. İyi: Kullanıcıya anlaşılır hata vermek. En İyi: İzleme sistemleriyle uyumlu structured JSON hata cevapları kullanmak.
Deploy Süreci	Kötü: Canlıya doğrudan elle deploy etmek. İyi: Test ortamında doğrulayıp canlıda deploy etmek. En İyi: CI/CD pipeline’ında onay mekanizması ve otomatik geriye alma planı tasarlamak.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Parola Rotasyonu	Parolaları düzenli aralıklarla yenileyin; gizli kasalarla entegre edin.
Erişim Yetkileri	Politikayı düzenleme yetkisini yalnızca güvenilir yöneticilere verin.
Audit Loglama	Token ekleme sonuçlarını loglayın; başarısız girişimler için SIEM uyarısı tetikleyin.
Şifreleme Standartları	PasswordDigest tercih edin; PasswordText yalnızca zorunlu durumlarda kullanılsın.
Nonce Kullanımı	Replay saldırılarını engellemek için nonce ve created kombinasyonunu aktif tutun.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Paylaşımlı Kimlik Bilgileri	Neden kaçınılmalı: Takip edilebilirlik ve güvenlik zafiyeti oluşur. Alternatif: Her servis için ayrı kullanıcı atayın.
Şifresiz Depolama	Neden kaçınılmalı: Konfigürasyon dosyalarında açık parola kalabilir. Alternatif: Şifre kasası veya çevresel değişken kullanın.
Test Edilmemiş Değişiklik	Neden kaçınılmalı: Canlı servisler hata verebilir. Alternatif: Canlıya geçmeden önce test ortamında doğrulayın.
Koşulsuz Uygulama	Neden kaçınılmalı: Gereksiz yük ve yanlış token eklenmesine yol açar. Alternatif: Path veya header tabanlı koşullar tanımlayın.

​

Performans İpuçları

Kriter	Öneri / Etki
Token Oluşturma Maliyeti	Öneri: PasswordDigest yalnızca gerekli olduğunda kullanın. Etki: Hash hesaplama yükü dengelenir.
Koşul Filtreleme	Öneri: Query Builder’da dar kapsamlı koşullar tanımlayın. Etki: Gereksiz token üretimlerinden kaçınılarak gecikme azaltılır.
Log Yönetimi	Öneri: Başarısızlık loglarını örnekleme ile toplayın. Etki: Log hacmi kontrol altında tutulur.
Politika Grupları	Öneri: Aynı token’i kullanan API’leri Policy Group ile gruplayın. Etki: Deploy süreleri kısalır, tutarlılık artar.
İzleme Metrikleri	Öneri: Token ekleme süresini APM metriklerine ekleyin. Etki: Performans anomalileri erken tespit edilir.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	WS Güvenliği Kullanıcı Adı Politikası hangi tip servislerde kullanılır?	SOAP ve WS-Security destekli servislerde kimlik doğrulaması gereken senaryolarda kullanılır.
Genel	Global politika değişikliği neden onay ister?	Global politikalar birden çok API’yi etkiler; onay verilmezse istenmeyen kesinti riski artar.
Teknik	PasswordDigest seçince parola nasıl korunur?	Parola nonce ve created ile hashlenerek gönderilir; düz metin tutulmaz.
Teknik	MustUnderstand alanı ne yapar?	Hedef servis WS-Security başlığının zorunlu olduğunu anlar; başlık yoksa isteği reddeder.
Kullanım	Farklı API Proxy (API Vekil Sunucusu) için farklı kullanıcı adı nasıl yönetilir?	Koşul tanımlayarak veya local politika oluşturarak her API için farklı yapılandırma kullanabilirsiniz.
Kullanım	Politika export dosyasını pipeline’da nasıl kullanırım?	ZIP dosyasını CI/CD aşamasına dahil edip import komutuyla otomatik dağıtım yapabilirsiniz.