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
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- 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ı?
- 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.
- 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.
- 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ü:
Createddamgası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: 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 4: 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 5: 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 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 UsernameToken parametresi tanımlı. 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 |
|---|---|
| Ç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. |