Plain-Text Kimlik Doğrulama
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?
- 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 | Durum: 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: 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: Kimlik Sağlayıcıyı Seçme | Kimlik/Yetki Doğrulama Servisi: - -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 5: 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: Gizli Anahtar/Parola Değerini Kontrol Et açıksa zorunlu olur; seçilen değişken gizli değeri tutar. |
| Adım 6: İstek İşleme Seçenekleri | Gizli Anahtar/Parola Değerini Kontrol Et: - Varsayılan olarak açıktır. Açıkken, kullanıcı adıyla birlikte bir gizli anahtar/parola değeri de sağlanmalı ve kontrol edilmelidir. - Kapatıldığında kimlik doğrulama yalnızca kullanıcı adı/API anahtarı değerine dayanır (yalnız-anahtar doğrulama) — ayrıca bir gizli değer kontrol edilmez. API Anahtarını Bearer Token Olarak Kullan (yalnızca Gizli Anahtar/Parola Değerini Kontrol Et kapalıyken görünür): - Açıkken, kullanıcı değişkeni üzerinden okunan değer (tipik olarak Authorization başlığı) Bearer <api-key> şemasını taşımak zorundadır; token'ın kendisi API anahtarı (Consumer kullanıcı adı / API Client clientId) olarak kullanılır.- Bearer şeması yoksa kimlik doğrulama başarısız olur.- Gizli Anahtar/Parola Değerini Kontrol Et tekrar açılırsa bu seçenek otomatik olarak kapatılır. - Kullanım örneği için aşağıdaki API Anahtarını Bearer Token Olarak Kullanma bölümüne bakın. İstemci Adresini Kontrol Et: Secret Manager senaryolarında IP eşlemesini zorlar. Yetkilendirme Bilgisini Temizle: Doğrulama sonrası Authorization header'ını target servise iletmeden temizler. Set Resolved Identity to Context (Çözümlenen Kimliği İstek Bağlamına Yaz): Bu politikanın çözümlediği kimliğin (kullanıcı/anahtar) isteğin kimliği olarak kaydedilip kaydedilmeyeceğini belirler. Açık (varsayılan) iken bu kimlik trafik loglarında ve sonraki politikalar ile scriptlerde görünür. Kapalı iken kimlik yalnızca gerekli iç kimlik doğrulama/yetkilendirme kontrolleri için kullanılır, isteğin kalıcı kimliği olarak tutulmaz. Kimliği Başlığa Ekle: Kullanıcı adını X-Authenticated-UserId (değiştirilebilir, Kimliğin Ekleneceği Başlık alanı) başlığıyla iletir.İstemci için ACL Kontrol Et: Varsayılan olarak açıktır. Yalnızca kimlik kaynağı Secret Manager olduğunda görünür. Kapalıyken politika yalnızca kimliği çözümler ve doğrular; tüketicinin bu API Proxy veya Proxy Group için erişim listesini (ACL) kontrol etmez. Bkz. Yalnızca Kimlik Modu (ACL Kapalı). |
| 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 kimlik sağlayıcı seçilmiş. Sonuç: - Politika listeye eklenir. - API'lere bağlanabilir. - Global politikaysa otomatik uygulanır. |
Varsayılan kullanıcı adı/parola modunda Kimlik/Yetki Doğrulama Servisi seçim listesinde OIDC Kimlik Sağlayıcı yer almaz: Plain-Text Kimlik Doğrulama her istekte gönderilen parolayı karşılaştırır, OIDC sağlayıcı ise token doğrular ve hiç parola vermez. API Anahtarını Bearer Token Olarak Kullan açıldığında (Gizli Anahtar/Parola Değerini Kontrol Et kapalıyken) sunulan değer bir bearer token olduğundan OIDC seçilebilir hale gelir: sağlayıcının ürettiği token her istekte sağlayıcının doğrulama moduna göre doğrulanır (çevrimdışı JWKS imzası, çevrimiçi introspection/userinfo), kimlik sağlayıcının Kullanıcı Adı Claim alanından çözülür ve Eşleşen Consumer Zorunlu Olsun açıksa bir Consumer ile eşlenir. API Anahtarını Bearer Token Olarak Kullan tekrar kapatılırsa OIDC kimlik kaynağı Secret Manager'a sıfırlanır (uyarı gösterilir); bearer modu kapalıyken OIDC kaynağı taşıyan politikayı sunucu reddeder. Tarayıcı tabanlı oturum açma akışları için OIDC Kimlik Doğrulama politikasını kullanın.
API Anahtarını Bearer Token Olarak Kullanma
API Anahtarını Bearer Token Olarak Kullan seçeneğini, yalnızca tek bir opak anahtar sunan ve kullanıcı adı/parola doğrulaması uygulamayan istemciler için etkinleştirin — örneğin, kendini tanıtmak için tam bir OIDC/Keycloak token alma akışına ihtiyaç duymaması gereken basit servisler arası veya makine istemcileri.
Gizli Anahtar/Parola Değerini Kontrol Et kapalı ve API Anahtarını Bearer Token Olarak Kullan açıkken, istek anahtarı standart Authorization header'ında Bearer şemasıyla taşımalıdır:
curl https://api.example.com/orders \
-H "Authorization: Bearer <api-key>"
Bearer sonrasındaki token, API anahtarı olarak aranır — seçilen Kimlik/Yetki Doğrulama Servisi'ne bağlı olarak Consumer'ın kullanıcı adı veya API Client'ın clientId değeri (OIDC kaynağında ise token, kimlik sağlayıcı tarafından doğrulanır). Bearer şeması olmayan veya token'ı boş olan bir istek, anahtar aranmadan önce reddedilir.
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.
Yalnızca Kimlik Modu (ACL Kapalı)
İstemci için ACL Kontrol Et kapalıyken politika yalnızca kimlik modunda çalışır. Kimliği yine çözümler ve doğrular; ancak tüketicinin bu API Proxy veya Proxy Group için erişim listesini (ACL) kontrol etmez.
| ACL kapalıyken yine uygulananlar | ACL kapalıyken atlananlar |
|---|---|
| Tüketici mevcuttur ve etkindir. Tüketicinin organizasyonu ve üst organizasyonları aktiftir. Tüketicinin geçerlilik süresi (expire date) dolmamıştır. Tüketicinin sözleşmeleri bitiş tarihini geçmemiştir. Parola veya secret doğrudur. İstemci IP'si tüketicinin IP listesindedir (Validate Client Address açıksa). API Client sahibi aktiftir. Rol yetkilendirmesi (etkinse) ve Limit Plan kuralları uygulanır. İstek doğrulanmış olarak işaretlenir ve çözümlenen kimlik trafik loguna yazılır. | Tüketicinin bu API Proxy veya Proxy Group için erişim satırı (süresi, ortam etkinleştirme anahtarı, izin verilmeyen method ve proxy'ler). API Client aboneliği ve erişim izinleri (portal abonelikleri). Bu bilgi erişim satırından geldiği için trafik logunda bu istekler için abonelik ürünü ve planı görünmez. |
ACL kapalıyken, kimlik kurallarını geçen ortamdaki her aktif tüketici API'yi çağırabilir. Proje sınırı yoktur.
Yalnızca anahtar modunda (Gizli Anahtar/Parola Değerini Kontrol Et kapalı) bilinen her API anahtarı API'yi çağırabilir.
LDAP, Database, API ve OIDC kimlik kaynakları ACL'yi hiçbir zaman sorgulamaz. Bu kaynaklarda seçeneğin etkisi yoktur.
Bir API Product'ın güvenlik sekmesinde, ACL'si kapalı politika mevcut "Politikadan yönetiliyor" durumuyla raporlanır: kimlik doğrulama consumer store (ACL) yerine politikadan yönetilir, bu nedenle uygulama credential'ları orada yetkilenmez.
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. |