Genel Bakış
Amacı Nedir?
- Plain Text Authentication başlığı taşıyan istekleri değerlendirerek, API Proxy (API Vekil Sunucusu) katmanında merkezi kimlik doğrulaması sağlar.
- Kurumsal kimlik servisleri (Database, LDAP, API, Secret Manager) ile entegre olup erişim politikasını kod değişikliği olmaksızın yönetilebilir hale getirir.
- Rol tabanlı yetkilendirme ve header enjeksiyonu ile uygulama katmanına gerekli kullanıcı/rol bilgisini güvenli şekilde aktarır.
- Hata mesajı özelleştirmesi ve koşul bazlı etkinleştirme sayesinde farklı endpoint veya ortam senaryoları için esnek davranış sunar.
Ç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ü: Plain Text Authentication 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ı?
- Kimlik Bilgisi Doğrulama: Authorization header’daki Plain Text kimlik bilgisi çözülür, seçilen kimlik sağlayıcı (Database/LDAP/API/Secret Manager) üzerinden kullanıcı adı ve opsiyonel olarak parola kontrol edilir; gerekirse kayıtlı IP adresi eşleştirilir.
- Karar Verme:
- Eşleşme Var: Kullanıcı yetkilendirme kurallarıyla uyuşur, isteğe kullanıcı/rol header’ları eklenir, backend’e yönlendirilir.
- Eşleşme Yok: Yetkilendirme başarısız olur, politika hata mesajı tetiklenir, isteğe izin verilmez.
- 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
- Kimlik Sağlayıcı Esnekliği: Database, LDAP, harici API veya Secret Manager tabanlı kimlik servisleriyle çalışır; seçilen kaynak değiştiğinde politika otomatik güncellenir.
- Kimlik Bilgisi Değişkenleri Yönetimi: Kullanıcı adı ve parola için proje değişkenlerini bağlayarak gizli değerleri merkezi olarak yönetir.
- Header Yönetimi: Doğrulanan kullanıcıyı
X-Authenticated-UserIdgibi özelleştirilebilir başlıklara ekler veya upstream’e geçmeden Authorization header’ını temizler. - 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
- Rol Bazlı Yetkilendirme: Rol gruplarını seçerek ALL/ANY mantığıyla kullanıcı erişimini sınırlar, isteğe rol listesi header’ı ekler.
- Metot Bazında Yetki Kuralları: API metodları bazında rol setleri ve yetkilendirme tipi tanımlayarak hassas endpoint’lere daha sıkı kontrol uygular.
- Secret Manager Entegrasyonu: Secret Manager seçildiğinde IP kontrolü ve otomatik değişken eşleşmesiyle sıfır kodlu güvenlik sağ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ç |
|---|---|---|---|
| Üretim LDAP Doğrulaması | Kurumsal LDAP ile giriş yapan kullanıcıları doğrulama ihtiyacı | Authentication provider olarak LDAP seçilir, checkPassword aktif edilir, roller LDAP üzerinden çekilir. | Geçerli kullanıcı/şifre kombinasyonu olmayan istekler 401 döner, başarılı olanlar yetkili ise 200 alır. |
| Secret Manager ile Makine Hesapları | Makine-makine entegrasyonunda paylaşılan sırlar Secret Manager’da saklanıyor | enumPolicyAuthenticationType SECRET_MANAGER, username/password değişkenleri otomatik çekilir, checkClientIpAddress aktif edilir. | Yanlış IP’den gelen veya eşlenmemiş sır kullanan istekler 403 ile reddedilir. |
| Database Kullanıcı Havuzu | Uygulama veritabanında tutulan kullanıcı listesiyle doğrulama | Database provider seçilir, rol tabloları bağlanır, addRolesToHeader aktif edilir. | Backend servisleri header üstünden rol bilgisine erişerek yetkilendirme yapar. |
| Harici API ile Kimlik Kontrolü | Kimlik doğrulaması üçüncü taraf REST servisine devredilmiş | API provider seçilir, servis endpoint’i tanımlanır, başarısız cevaplar için özel hata mesajı düzenlenir. | Harici API “fail” dönerse politika 401 yanıtlar, başarılı ise header’lara kullanıcı ID eklenir. |
| Rol Bazlı Yetki Modülü | Belirli endpoint’lere sadece belirtilen roller erişsin | Authorization modülü açılır, rol setleri ve ALL şartı atanır, yetkisiz mesaj özelleştirilir. | Gerekli role sahip olmayan kullanıcılara 403 ve özel mesaj döner. |
| Metot Özel Yetki | /admin/* metodları sadece belirli role açık | Method Access aktif edilir, ilgili API metodlarına rol listesi bağlanır. | Sadece tanımlanan rol listesine sahip kullanıcılar metodu çağırabilir. |
| API Proxy Grubunda Standartlaştırma (opsiyonel) | Aynı güvenlik politikasını çoklu API Proxy üzerinde uygulama | Politika Policy Group’a eklenir, Proxy Group’a bağlanır, merkezi deploy yapılır. | Tüm bağlı API Proxy örnekleri aynı Plain Text Authentication kuralını kullanır. |
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 Plain Text Authentication 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 → Plain Text Authentication 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_PlainTextAuth- 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: “Üretim servisi için Plain Text Authentication kuralı” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Kimlik Sağlayıcıyı Seçme | Identity Role Group: - -Select butonuyla Database, LDAP, Secret Manager veya harici API sağlayıcısını seçin. - Seçimi temizlemek için çarpı butonunu kullanın. - Secret Manager seçildiğinde politika otomatik olarak bu kaynağa bağlanır. |
| Adım 4: Kimlik Bilgisi Değişkenlerini Atama | Username Variable: Proje değişkenlerinden kullanıcı adı girdisini bağlayın. Güncelle veya farklı değişken seç seçenekleriyle değişiklik yapın. Password Variable: checkPassword işaretliyse zorunlu olur; seçilen değişken gizli değeri tutar. |
| Adım 5: İstek İşleme Seçenekleri | Check Password: Kapalıysa sadece kullanıcı adı doğrulanır, parolaya bakılmaz. Check Client IP Address: Secret Manager senaryolarında IP eşlemesini zorlar. Clear Authorization Header: Doğrulama sonrası Authorization header’ını target servise iletmeden temizler. Add User To Header: Kullanıcı adını X-Authenticated-UserId (değiştirilebilir) başlığıyla iletir. |
| 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 kimlik sağlayıcı seçilmiş. 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 |
|---|---|
| Secret Manager Tabanlı Doğrulama | - Secret Manager seçildiğinde kimlik bilgileri otomatik eşlenir. - checkClientIpAddress ile token başına IP sınırı uygulanır.- Şifre rotasyonu yapıldığında politika otomatik güncellenir. |
| Hybrid Yetkilendirme Yapısı | - Authentication kaynağı ile Authorization kaynağı farklı seçilebilir (ör: LDAP + Database). - Ayrı provider seçimi Authorization Configuration bileşeninden yapılır. - Roller MultiSelect ile tanımlanır, ALL/ANY seçicisi uygulanır. |
| Metot Bazlı Kısıtlama Motoru | - enableMethodAccess aktif edildiğinde API metodları listelenir.- Her metod için rol listesi ve yetkilendirme tipi atanır. - Reverse Proxy dışındaki API Proxy modlarında istek bazlı kurallar uygulanır. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Kimlik Sağlayıcı Seçimi | Kötü: Tüm politikaları tek bir Secret Manager hesabına bağlamak. İyi: Uygulama tipine göre Secret Manager veya LDAP seçmek. En İyi: Her ortam için ayrı provider kullanıp erişim izinlerini kısıtlamak. |
| Değişken Yönetimi | Kötü: Username/password değişkenlerini manuel eşlemek. İyi: Varsayılan proje değişkenlerini kullanmak. En İyi: Secret Manager senaryosunda değişkenleri per API Proxy olacak şekilde versiyonlamak. |
| Header Kullanımı | Kötü: Kullanıcı bilgilerini varsayılan header adlarında bırakmak. İyi: Header adını tüketici uygulamalara göre güncellemek. En İyi: Rol ve kullanıcı header’larını TLS altındaki güvenli kanalda taşımak, log’larda maskelemek. |
| Authorization Kurgusu | Kötü: Rol tablosunu boş bırakıp sadece kimlik doğrulamaya güvenmek. İyi: Temel rol setlerini ALL kuralıyla tanımlamak. En İyi: Method Access’i aktif edip hassas metotlara ayrı rol listesi atamak. |
| Politika Yaşam Döngüsü | Kötü: Üretim değişikliklerini direkt canlıda yapmak. İyi: Test ortamında aynı politikayı localize edip denemek. En İyi: Export/Import ile sürüm oluşturup Deploy sonrası kullanım raporlarını izlemek. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Credential Yönetimi | Kimlik bilgilerini sadece Secret Manager veya şifreli değişkenlerde saklayın; politika ekranına düz metin değer girmeyin. |
| Header Hijacking Önlemleri | addUserToHeader aktifse backend tarafında header doğrulaması yapın, client manipülasyonuna karşı reverse proxy’de header overwrite’i kapatın. |
| Yetkilendirme Konsolidasyonu | Authorization modülü açıldığında roller ve method kuralları güncel tutulmazsa %100 yetki dışı erişim riski doğar; düzenli audit yapın. |
| IP Kısıtlaması | Secret Manager IP doğrulaması sadece güvenilen kaynak IP’lerini kabul eder; değişiklik öncesi whitelist güncelleyin. |
| Hata Mesajı Hijyeni | 401/403 cevaplarında kullanıcıya spesifik bilgi vermeyin; hata mesajlarını genel bırakın, ayrıntıyı loglarda tutun. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Yanlış Provider Seçimi | Neden kaçınılmalı: LDAP yerine Database seçmek kimlik verisindeki field farklarından dolayı başarısız doğrulama üretir. Alternatif: Provider seçmeden önce kullanıcı kaynağını doğrulayın. |
| Değişkensiz Parola Kontrolü | Neden kaçınılmalı: checkPassword açıkken parola değişkeni boş ise politika her isteği reddeder.Alternatif: Parola değişkenini zorunlu alan kontrolüyle eşleştirin. |
| Header Temizlemeyi Atlamak | Neden kaçınılmalı: Authorization header’ın backend’e iletilmesi güvenlik açığı yaratabilir. Alternatif: clearAuth seçeneğini aktif kullanın. |
| Global Değişiklikleri Doğrudan Deploy Etmek | Neden kaçınılmalı: Çoklu API Proxy aynı anda etkilenir, servis kesintisi doğabilir. Alternatif: Önce lokalize edip test edin, sonra global politikayı güncelleyin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Kimlik Kaynağı Yanıt Süresi | Öneri: LDAP/Database sorgularında indeksleri optimize edin. Etki: Doğrulama süresi kısalır, Gateway bekleme süresi azalır. |
| Secret Manager Çağrıları | Öneri: Secret Manager yanıtlarını Cache mekanizmasıyla kısa süreli saklayın. Etki: Tekrarlayan kimlik doğrulamalarında latency düşer. |
| Harici API Kullanımı | Öneri: Harici kimlik API’sine Timeout ve Retry limitleri ekleyin. Etki: Uzun süren çağrılar Gateway thread’lerini bloke etmez. |
| Rol Listesi Boyutu | Öneri: Gereksiz rol atamalarını azaltın, MultiSelect listesini temiz tutun. Etki: Authorization kontrolü daha hızlı çalışır, hafıza kullanımı azalır. |
| Method Access Yoğunluğu | Öneri: Sık kullanılan endpoint’ler için method bazlı kuralları gruplayın, gerekmeyen metodlarda kapatın. Etki: Policy değerlendirme süresi kısalır, CPU yükü düşer. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Plain Text Authentication politikası hangi senaryolarda tercih edilmeli? | Basit kullanıcı adı/parola doğrulamasının yeterli olduğu, uygulama katmanına minimum değişiklikle güvenlik eklemek istediğiniz tüm API Proxy akışlarında kullanılabilir. |
| Genel | clearAuth seçeneği ne işe yarar? | Doğrulama tamamlandıktan sonra Authorization header’ını backend’e iletmeden temizler; böylece hassas bilgiler servisler arasında dolaşmaz. |
| Teknik | Parola kontrolünü kapatırsam ne olur? | Gateway sadece kullanıcı adını doğrular; parola doğrulanmadığı için hesap kilidi veya brute-force kontrolleri devre dışı kalabilir. |
| Teknik | Secret Manager senaryosunda IP denetimi nasıl çalışır? | Token veya değişkenle birlikte kayıtlı IP listesi kontrol edilir; IP eşleşmezse politika 403 döndürür. |
| Kullanım | Kullanıcı bilgisi header adını değiştirebilir miyim? | addUserToHeader etkinleştirildiğinde userHeaderName alanından istediğiniz header adını belirleyebilirsiniz. |
| Kullanım | Rol bazlı yetkilendirmeyi aktif ettiğimde mevcut API Proxy’lere etkisi ne olur? | Politika bağlı olduğu tüm API Proxy akışlarında gelen isteğin rol listesini kontrol eder; koşullara uymayan istekler 403 döner, loglarda detay görülür. |