Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) akışlarından geçen SAML assertion’larını doğrulayarak kimlik federasyonunu merkezileştirir.
- Kullanıcı veya sistem SSO taleplerinde yalnızca güvenilir imzacıların kabul edilmesini sağlayarak erişim güvenliğini artırır.
- JKS tabanlı key store yönetimi sayesinde sertifika rotasyonlarının merkezi olarak kontrol edilmesine imkân tanır.
- XPath tabanlı temizleme ile doğrulanan SAML bloklarının aşağı akış servislerine sızmasını engeller ve veri gizliliğini korur.
Ç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ü: SAML Doğrulama 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ı?
- SAML Doğrulama Kontrolü: İstek gövdesindeki SAML assertion seçili key store’daki sertifikalarla imza doğrulamasından geçirilir; gerekli ise XPath ifadesiyle ilgili XML düğümü temizlenir.
- Karar Verme:
- Eşleşme Var: İmza doğrulanırsa istek, güncellenmiş payload ile akışın bir sonraki adımına yönlendirilir.
- Eşleşme Yok: İmza doğrulaması başarısızsa veya key store bulunamazsa istek durdurulur ve özelleştirilebilir hata yanıtı döndürülü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
- Key Store Doğrulaması: JKS formatındaki key store içindeki sertifikalarla SAML imza doğrulaması gerçekleştirir; key store seçilmeden kayıt yapılamaz.
- Bilinmeyen İmzacı Toleransı:
allowUnknownSignerseçeneğiyle bilinen CA zincirine bağlı olmayan sertifikaların kontrollü biçimde kabul edilmesini sağlar. - XPath Tabanlı SAML Temizleme:
clearSamlveclearSamlPathalanlarıyla doğrulama sonrası mesaj gövdesindeki SAML bloklarını temizleyerek veri sızıntısını engeller. - 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
- Dinamik Key Store Yönetimi: Yapılandırma ekranından yeni key store oluşturma dialog’u çağırarak sertifika setlerini anında üzerinde çalıştığınız projeye ekler.
- XPath Test Otomasyonu: Test Transformation Data bileşeniyle
clearSamlPathifadesini gerçek veri örnekleri üzerinde test ederek yanlış temizleme riskini azaltır. - Varsayılan İmza Düğümü Algısı:
clearSamlPathaktif edildiğinde varsayılan imza düğümü XPath’i otomatik atanır ve ihtiyaç halinde özelleştirilebilir. - 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 SSO Entegrasyonu | Kurum içi IdP’den gelen SAML assertion’ları mikroservislere yönlendirilecek | Key store olarak kurumsal CA sertifikası seçilir, clearSaml kapalı tutulur. | Doğrulanan SAML assertion diğer Policy adımlarına geçer. |
| SaaS Yetkilendirme Geçidi | SaaS sağlayıcısından gelen SAML’de üçüncü taraf sertifikalar mevcut | allowUnknownSigner aktif edilir, condition ile ilgili endpoint hedeflenir. | Yetkisiz sertifikalar kabul edilir ancak diğer koşullar sağlanmazsa reddedilir. |
| SAML Veri Maskesi | Mesaj gövdesinde SAML assertion kalmaması gerekiyor | clearSaml aktif, clearSamlPath firma standardına göre güncellenir. | Doğrulama sonrası SAML bloğu temizlenmiş payload downstream servise gider. |
| Test Ortamı Doğrulama | Geliştirme ortamında self-signed sertifika kullanılıyor | Ayrı bir test key store import edilir, condition ile ortam header’ına bağlanır. | Sadece test isteğinde self-signed kabul edilir, canlıda reddedilir. |
| Key Store Rotasyonu | Sertifikaların periyodik yenilenmesi gerekiyor | Yeni key store import edilir, eski key store condition ile devre dışı bırakılır. | Kesinti olmadan sertifika geçişi yapılır. |
| Hata Mesajı Lokalizasyonu | Farklı istemcilere özel hata mesajı gösterilecek | Error Message Customization sekmesinde locale bazlı mesajlar tanımlanır. | İstemci diline göre özelleştirilmiş 4xx yanıtları döner. |
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 SAML Doğrulama 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 → SAML Doğrulama 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_SAMLValidation- 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: “Kurumsal IdP SAML doğrulaması” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Key Store ve İmza Doğrulama Yapılandırması | - Gerekli JKS key store’u seçin veya yeni key store oluştur dialog’unu açın. - Key store seçilmeden kayıt işlemi tamamlanmaz. - AllowUnknownSigner seçeneğini gereksinime göre aktif edin. |
| Adım 4: SAML Temizleme Ayarları (Varsa) | - clearSaml seçeneğini açarak doğrulanan SAML düğümünü temizleyin.- clearSamlPath alanını kendi XML yapınıza göre güncelleyin; gerekirse varsayılan XPath’i koruyun. |
| Adım 5: XPath Testi ve Varsayılanları (Varsa) | - Test Transformation Data bileşeniyle clearSamlPath ifadesini örnek payload üzerinde çalıştırın, yanlış düğüm silinmesini engelleyin. |
| 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 |
| 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 SAML doğrulama gerekliliği (key store seçimi, opsiyonel XPath) mevcut 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 |
|---|---|
| Key Store Diyalog Entegrasyonu | - Key store listeleme alanından yeni kayıt oluşturma butonunu açın. - Yeni JKS dosyasını içeri aktarın ve zorunlu alanları doldurun. - Oluşan key store otomatik olarak politika formuna set edilir. |
| XPath Temizleme Testi | - clearSamlPath alanını doldurduktan sonra test butonuna basın.- Örnek XML verisiyle XPath sonucu önizleyin. - Yanlış düğüm seçimi tespit edilirse XPath’i güncelleyin. |
| Global Politika Lokalizasyonu | - Detay ekranından Localize butonuna tıklayın. - Local kopyada koşulları ve key store’u yeni ortama göre düzenleyin. - Gerekiyorsa global sürümü güncelleyip yeniden deploy edin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Key Store Yönetimi | Kötü: Key store’u manuel kopyalanmış JKS dosyalarıyla güncellemek. İyi: Her ortama ait ayrı JKS sürümü tutmak. En İyi: Otomatik sertifika rotasyonu ve expiration takibi için merkezi key store yönetimi kullanmak. |
| XPath Bakımı | Kötü: Varsayılan XPath’i her payload için değiştirmeden bırakmak. İyi: XPath’i gerçek XML yapısına göre uyarlamak. En İyi: Test Transformation Data ile her değişiklikte doğrulamak ve sürüm kontrolünde saklamak. |
| Hata Mesajı Tasarımı | Kötü: Genel 500 mesajı döndürmek. İyi: 401/403 kodlarına özel açıklamalar eklemek. En İyi: Hata kodlarını istemci türüne göre özelleştirip lokalizasyon yapmak. |
| Koşul Tasarımı | Kötü: Politikanın tüm trafiğe uygulanması. İyi: Endpoint bazlı koşullar tanımlamak. En İyi: Ortam, istemci ve Method bazlı birleşik koşullar ile granular kontrol sağlamak. |
| Ortamlar Arası Taşıma | Kötü: Production key store’u Geliştirme ortamına kopyalamak. İyi: Ortam bazlı key store setleri hazırlamak. En İyi: Export/Import süreçlerinde isimlendirme standardı ve bağımlılık kontrolü uygulamak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Sertifika Yaşam Döngüsü | JKS dosyalarının son kullanma tarihini takip edin, expiration yaklaşınca önceden yenileyin. |
| İmza Doğrulama Politikaları | allowUnknownSigner özelliğini sadece geçici gereksinimlerde açın, aksi halde güvenilmeyen sertifikalar kabul edilebilir. |
| Key Store Erişim Yetkisi | Key store yönetimini yetkili DevOps kullanıcılarıyla sınırlandırın, erişim loglarını saklayın. |
| Payload Temizliği | clearSamlPath kullanımı sonrası çıktıyı loglayarak hassas verinin sistem dışına çıkmadığından emin olun. |
| Hata Mesajı Maskeleme | Hata mesajlarında assertion detaylarını göstermeyin, istismar riskini azaltın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Yanlış Key Store | Neden kaçınılmalı: Yanlış JKS seçmek tüm doğrulamaları başarısız kılar. Alternatif: Ortama uygun key store’ları etiketleyip doğru listelemeyi sağlayın. |
| Genel XPath Kullanımı | Neden kaçınılmalı: Varsayılan XPath her şemada çalışmaz ve yanlış düğümü silebilir. Alternatif: Her payload tipi için doğrulanmış özel XPath tanımlayın. |
| Sürekli Allow Unknown Signer | Neden kaçınılmalı: Güvenlik duvarından sızan sertifikalar kabul edilebilir. Alternatif: Sadece geçici testlerde açın, sonra kapatın. |
| Koşulsuz Uygulama | Neden kaçınılmalı: Gereksiz doğrulama yükü ve hatalı bloklama oluşur. Alternatif: Query Builder ile hedef endpoint veya header bazlı koşullar belirleyin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Key Store Boyutu | Öneri: Gereksiz sertifikaları JKS’den temizleyin. Etki: Doğrulama süresi kısalır. |
| XPath Karmaşıklığı | Öneri: Basit ve spesifik XPath ifadeleri kullanın. Etki: XML parse ve temizleme süresi azalır. |
| Koşul Filtreleme | Öneri: Politika sadece gerekli endpoint ve metotlarda çalışsın. Etki: Gateway üzerindeki CPU yükü düşer. |
| Log Düzeyi | Öneri: Debug loglarını Production’da kapalı tutun. Etki: IO yükü ve gecikme azalır. |
| Hata Mesajı Özelleştirme | Öneri: Sık kullanılan hata yanıtlarını cache’leyin. Etki: Yanıt oluşturma süreleri düşer. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | SAML Doğrulama politikası hangi ağ akışlarında kullanılmalı? | Kimlik federasyonu yapılan ve SAML assertion taşıyan tüm API Proxy akışlarında kullanılmalıdır. |
| Genel | Key store olmadan politika kaydedilebilir mi? | Hayır, zorunlu olarak bir JKS key store seçilmelidir. |
| Teknik | allowUnknownSigner aktif olduğunda başka kontrol yapılır mı? | Politikadaki koşullar ve diğer Policy adımları çalışmaya devam eder, sadece sertifika zinciri kontrolü esnekleşir. |
| Teknik | clearSamlPath alanı boş bırakılırsa ne olur? | clearSaml açıkken alan boş ise doğrulama başarısız olur ve politika kaydedilemez. |
| Kullanım | XPath test fonksiyonu Production’da kullanılabilir mi? | Evet, ancak örnek payload girişi yaparken hassas verileri maskeleyin. |
| Kullanım | Global politikayı local kopyaya dönüştürdükten sonra ne değişir? | Local kopya sadece seçilen API Proxy için geçerli olur ve global sürümdeki güncellemeler local kopyayı etkilemez. |