Genel Bakış
HTTP Digest kimlik bilgilerini doğrular, isteğe özel başlık ve yetkilendirme seçenekleri sağlar.Amacı Nedir?
- Dizinde saklanan Secret Manager değişkenleriyle eşleştirerek gelen HTTP Digest kimlik doğrulamasını zorunlu kılmak ve anonim erişimi engellemek.
- İsteğin Authorization başlığını kontrol edip, upstream servisler için güvenli kullanıcı kimliği ve rol aktarımı sağlamak.
- Opsiyonel istemci IP doğrulaması ve Clear Auth gibi ek kontrollerle saldırı yüzeyini azaltmak.
- Dahili yetkilendirme motoru veya harici servislerle entegre olarak rol bazlı erişim kararlarını merkezileştirmek.
- Hata mesajı ve koşul bazlı çalıştırma seçenekleriyle politikanın farklı ortam gereksinimlerine uyarlanmasını sağlamak.
Ç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ü: Digest Kimlik 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ı?
- Digest Kimlik Doğrulama Kontrolü: Authorization header içindeki digest parametreleri çözümlenir, username/password/nonce/created değişkenleri Secret Manager üzerinden alınır ve RFC uyumlu özet karşılaştırması yapılır; değişkenlerden biri eksikse istek hemen reddedilir.
- Karar Verme:
- Eşleşme Var: Kullanıcı tanımlıysa isteğe devam edilir, Clear Auth kapalıysa orijinal başlık saklanır, Add User to Header aktifse kullanıcı bilgisi istenen header’a eklenir, yetkilendirme açıksa rol listesi hesaplanır.
- Eşleşme Yok: Varsayılan veya özelleştirilmiş hata yanıtı hazırlanır, isteğin iletimi durdurulur, yetkilendirme çağrıları tetiklenmez.
- 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
- Secret Manager Değişken Yönetimi: Kullanıcı adı, parola, nonce ve created değerleri Apinizer Secret Manager değişkenleriyle ilişkilendirilir; değişken güncellemeleri tek noktadan yönetilir.
- Authorization Header İşleme: Clear Auth seçeneği ile doğrulama sonrası hassas kimlik bilgileri upstream servislere geçmeden silinebilir.
- İstemci IP Doğrulaması: checkClientIpAddress parametresiyle talep eden IP’nin kayıtlı kimlik bilgisiyle eşleşmesi sağlanarak paylaşım saldırıları engellenir.
- 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
- Yetkilendirme Katmanı Entegrasyonu: AuthorizationConfiguration bileşeniyle LDAP, veritabanı veya REST API tabanlı rol doğrulaması eklenebilir, roller header’a taşınabilir.
- Metot Bazlı Erişim Kısıtlama: enableMethodAccess sayesinde HTTP metoduna göre rol zorunluluğu tanımlanır, hassas işlemler ayrı korunur.
- Secret Manager Senkronizasyonu: Otomatik variable seçimi, digest politikalarına özgü username/password/nonce/created varsayılanlarını hızla yükler.
- 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 Portal | Yalnızca kayıtlı kullanıcılar portal arayüzüne erişebilmeli | Username/password/nonce/created değişkenleri Secret Manager’dan seçilir, Add User to Header aktif edilir | Başarılı kullanıcı bilgisi X-Authenticated-UserId başlığına taşınır, diğer istekler 401 döner |
| Operasyon API’si | Operasyon ekip IP listesi dışında erişim olmamalı | checkClientIpAddress aktif edilir, IP değişkenleri Secret Manager’da güncellenir | Liste dışı IP’den gelen digest istekleri 401 döner, loglanır |
| Üçüncü Parti Entegrasyon | Partner servis rol bazlı yetkiye ihtiyaç duyuyor | enableAuthorization açılır, Authorization API seçilir, roller header’a eklenir | Doğrulanan kullanıcı rolleri X-Authenticated-UserRoles içinde upstream servise iletilir |
| Canlı Bakım Zamanı | Bakımda geçici olarak digest devre dışı bırakılmalı | Politika pasif yapılır, açıklamaya bakım notu eklenir | İstekler digest kontrolü olmadan geçer, bakım sonrası tekrar aktive edilir |
| Mikroservis Güvenliği | Bazı endpoint’lerde ek güvenlik gerekiyor | Query Builder ile /admin/* path’ine koşul eklenir, Clear Auth kapatılır | Sadece yönetim endpoint’lerinde digest çalışır, diğerlerinde politika devreye girmez |
| Test Ortamı Simülasyonu | QA ortamında farklı kullanıcı seti kullanılacak | Export alınır, test ortamında import edilip Secret Manager değişkenleri QA kullanıcılarıyla güncellenir | QA ortamı kendi digest kimlik bilgileriyle izole çalışı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.Yeni Digest Kimlik 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 → Digest Kimlik Doğrulama 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_DigestAuth- 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: “Canlı ortam için digest kimlik doğrulaması” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Secret Manager Değişkenlerini Seçme | Username, Password, Nonce ve Created değişkenlerini sırasıyla belirleyin. - Değişken diyaloglarıyla mevcut kayıtları güncelleyebilir veya yenilerini seçebilirsiniz. - Her dört değişken seçilmeden politika kaydedilmez. |
| Adım 4: İstemci Kontrollerini Ayarlama | Clear Auth: - Checkbox aktif edilirse, upstream servise gönderilmeden önce Authorization başlığını temizler. - Mikroservis mimarilerinde backend’in şifre bilgisine erişmesini engellemek için kullanılır. Check Client IP Address: - Checkbox aktif edilirse, IP kontrolü yapılır. - Kimlik bilgisi paylaşımını engeller. |
| Adım 5: Başlık ve Yetkilendirme Yapılandırması | Add User to Header: - Toggle aktif edilirse, doğrulanan kullanıcı bilgisi özel header ile backend’e iletilir. - User Header Name alanı açılır (varsayılan: X-Authenticated-UserId).AuthorizationConfiguration: - Yetkilendirme Kaynağı, rol başlığı ve metot kısıtlarını tanımlayın. |
| 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 digest değişken seti seçili Sonuç: - Politika listeye eklenir. - API Proxy (API Vekil Sunucusu)‘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 |
|---|---|
| Yetkilendirme Kaynağı Senaryoları | - AuthorizationConfiguration bileşeninden LDAP, Database veya API kaynağını seçin. - Rol eşlemesi için credentialRoleIdList listesini doldurun. - Use Secret Manager seçeneği ile hassas bağlantı bilgilerini yönetilebilir değişkenlerde tutun. |
| Metot Bazlı Erişim Kontrolü | - enableMethodAccess seçeneğini aktif edin. - policyAuthorizationMethodDefList altında HTTP metodunu ve gerekli rolü eşleştirin. - Yetkisi olmayan metod çağrıları için özel hata mesajı tanımlayın. |
| Rol Başlığı Yerleşimi | - addRolesToHeader seçeneğini işaretleyin. - rolesHeaderName alanını hedef servisin beklediği başlığa göre güncelleyin. - Başarılı doğrulamada roller otomatik olarak oluşturulmuş başlıkta iletilsin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Secret Manager Yönetimi | Kötü: Digest kullanıcılarını düz metinle saklamak İyi: Secret Manager’de değişken oluşturmak En İyi: Değişkenlere erişimi RBAC ile sınırlandırmak |
| Authorization Header Kullanımı | Kötü: Clear Auth kapalıyken hassas başlığı ilerletmek İyi: Clear Auth’ı hassas entegrasyonlarda aktif tutmak En İyi: Clear Auth artı özel log maskeleme uygulamak |
| Koşul Tasarımı | Kötü: Politikanın her isteğe uygulanması İyi: Yalnızca yönetim endpoint’lerine koşul koymak En İyi: Koşulları ortam, metot ve header kombinasyonlarına göre optimize etmek |
| Rol İletimi | Kötü: Roller olmadan downstream yetkilendirmeye güvenmek İyi: Roller için default header kullanmak En İyi: Add Roles to Header + imzalı header validasyonu uygulamak |
| Versiyonlama | Kötü: Değişiklikleri kaydetmeden önce yedek almamak İyi: Export alıp saklamak En İyi: Export dosyalarını kurumsal versiyon yönetiminde arşivlemek |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Kimlik Bilgisi Koruması | Secret Manager erişimlerini denetleyin, değişkenleri uygulama kaynak koduna gömmeyin. |
| Replay Koruması | Nonce ve created değerlerini zorunlu kılın, loglarda maskeleyin. |
| IP Whitelisting | checkClientIpAddress seçeneğini, sabit IP’li tüketicilerde etkinleştirin. |
| Log Maskeleme | Authorization başlığını log’larken özetleyin veya maskeleme kuralları uygulayın. |
| Yetkilendirme Denetimi | enableAuthorization açıkken, rol eşlemelerinin güncel olduğundan emin olmak için düzenli audit yapın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Eksik Değişken Tanımı | Neden kaçınılmalı: Zorunlu digest alanları olmadan politika istekleri reddeder. Alternatif: Tüm değişkenleri Secret Manager’dan seçip test edin. |
| Yanlış Header Adı | Neden kaçınılmalı: Upstream servis kullanıcı kimliğini okuyamaz. Alternatif: userHeaderName’i hedef servisin beklediği adla eşleştirin. |
| Kontrolsüz Clear Auth Kapalı Kullanımı | Neden kaçınılmalı: Authorization başlığı iç ağda gereksizce yayılır. Alternatif: Clear Auth’ı açıp gerekli bilgileri özel header’da taşıyın. |
| Test Edilmemiş Authorization Kuralları | Neden kaçınılmalı: Yanlış rol atamaları üretim kesintisine yol açabilir. Alternatif: Rolleri Geliştirme ortamında senaryo bazlı test edin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Secret Manager Erişimi | Öneri: Sık kullanılan değişkenleri Secret Manager cache’ine alın. Etki: Kimlik doğrulama gecikmesi azalır. |
| Authorization Servis Çağrıları | Öneri: Harici yetkilendirme API’sini düşük gecikmeli halde tutun. Etki: Toplam politika yanıt süresi düşer. |
| Koşul Değerlendirme | Öneri: Query Builder’da gereksiz OR bloklarını temizleyin. Etki: İstek başına koşul değerlendirme süresi kısalır. |
| Loglama Seviyesi | Öneri: Başarılı isteklerde log seviyesini INFO yerine DEBUG’a çekin. Etki: Yüksek trafikte log yazma maliyeti azalır. |
| Rol Dağıtımı | Öneri: Role header’larını yalnızca enableAuthorization aktifken üretin. Etki: Gereksiz header oluşturma yükü ortadan kalkar. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Digest Kimlik Doğrulama Politikası hangi isteklerde devreye girer? | Politika aktif ve koşulları sağlanan tüm HTTP/HTTPS isteklerinde Authorization header’ı kontrol eder. |
| Genel | Clear Auth ne zaman kullanılmalı? | Upstream servislerin digest header’ına ihtiyaç duymadığı, yalnızca kullanıcı kimliğine ihtiyaç duyduğu durumlarda etkinleştirilmelidir. |
| Teknik | Secret Manager değişkeni nasıl seçiliyor? | Variable diyalogu ile mevcut değişkenler listelenir, seçilen kayıt otomatik olarak ilgili alanla eşleştirilir. |
| Teknik | Authorization entegrasyonu başarısız olursa ne olur? | Yetkilendirme hata döndürürse politika 403 Forbidden üretir ve özelleştirilmiş hata mesajı tetiklenir. |
| Kullanım | Aynı kullanıcı için farklı nonce değerleri desteklenir mi? | Evet, nonce değişkeni Secret Manager’da dinamik güncellenebilir; replay koruması için únicos değerler önerilir. |
| Kullanım | Politika yerelleştirilince ne değişir? | Localize işlemi global politikayı kopyalar, yeni politika yalnızca seçilen API Proxy (API Vekil Sunucusu) içinde düzenlenir. |