SAML Kimlik Doğrulama

ipucu

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?

• 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

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. 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ı?
3. 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.
4. 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.
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

• 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ı: allowUnknownSigner seçeneğiyle bilinen CA zincirine bağlı olmayan sertifikaların kontrollü biçimde kabul edilmesini sağlar.
• XPath Tabanlı SAML Temizleme: clearSaml ve clearSamlPath alanları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 clearSamlPath ifadesini gerçek veri örnekleri üzerinde test ederek yanlış temizleme riskini azaltır.
• Varsayılan İmza Düğümü Algısı: clearSamlPath aktif 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: 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: 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 5: 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 6: 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 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
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 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.

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
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.