Genel Bakış
Amacı Nedir?
- Merkezi JWT üretimini standardize etmek: Farklı istemci tipleri için güvenilir JWT oluşturma akışını Apinizer üzerinde toplar.
- Kimlik doğrulama kaynaklarını yönetmek: Secret Manager, LDAP, Database veya API tabanlı kimlik doğrulama servislerini seçilebilir hale getirir.
- Yetkilendirme entegrasyonunu kolaylaştırmak: Rol ve yöntem bazlı yetkilendirmeyi JWT üretimi ile aynı politika üzerinde koordine eder.
- Operasyonel denetimi sağlamak: Token süreleri, yenileme hakları ve header aktarımlarını merkezi olarak kontrol ederek audit ve izlenebilirlik 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ü: JWT 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ı?
- JWT Üretim ve Doğrulama Süreci: Seçilen grant type’a göre kimlik doğrulama kaynağı tetiklenir, imzalama algoritması uygulanır, token ömrü ve refresh hakları hesaplanır.
- Karar Verme:
- Eşleşme Var: Token oluşturulur veya doğrulanır, gerekirse kullanıcı/rol header’ları eklenerek hedef servise yönlendirilir.
- Eşleşme Yok: Varsayılan veya özelleştirilmiş hata mesajı ile istek reddedilir; yenileme tokenı üretimi/iptali yapılmaz.
- 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
- Grant Type Yönetimi: Client Credentials ve Password grant tipleri arasında hızlı geçiş, her tip için gerekli kimlik doğrulama bileşenlerinin otomatik denetlenmesi.
- Kimlik Kaynağı Seçimi: Secret Manager, LDAP, Database veya harici API kaynaklarını JWT üretim sürecine entegre eder.
- Token Yaşam Döngüsü Kontrolü: Token ömrü, yenileme hak sayısı ve süreleri için ayrıntılı yapılandırma ve varsayılan değer atamaları.
- 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
- JWT İmza Algoritmaları: RS256, RS384, RS512 seçenekleri ile hedef sistem gereksinimlerine uygun imzalama sağlar.
- Header Enjeksiyonu: Kullanıcı kimliği ve rol bilgilerini istenilen header isimleriyle hedefe taşır; role-based yetkilendirme ile entegre çalışır.
- Refresh Token Politikaları: Yenileme token’ı üretimi, kullanım limiti ve süreleri üzerinden güvenlik/konfor dengesi kurar.
- Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Geliştirme, 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ç |
|---|---|---|---|
| Mobil İstemci JWT Dağıtımı | Mobil uygulamalar ayrı client kimlikleri ile bağlanacak | Grant Type: CLIENT_CREDENTIALS, Secret Manager seçili, token süresi 30 dk | Her mobil istemciye otomatik JWT üretilir, backend doğrulaması sorunsuz |
| Yetkili Kullanıcı Oturumu | Kullanıcı adı/şifre ile giriş yapılıyor | Grant Type: PASSWORD, LDAP kaynağı, token 15 dk + refresh 2 kez | LDAP doğrulaması sonrası JWT üretilir, refresh ile oturum 45 dk uzar |
| Mikroservisler Arası İletişim | Arka planda servisler birbirini çağırıyor | Grant Type: CLIENT_CREDENTIALS, allowUrlParameters kapalı, header aktarımı aktif | Servisler sadece header üzerinden token taşır, URL sızıntısı engellenir |
| Coğrafi Kısıtlı Giriş | Belirli konumlardan gelen talepler kabul edilecek | Condition: Geolocation header kontrolü, checkClientIpAddress açık | İzin verilen IP/konumlar JWT alır, diğerleri 403 döner |
| JWT Yenileme Tosması | Refresh token sayısı sınırlanmalı | RefreshTokenAllowed true, Count=2, süresi 24 saat | Kullanıcı 2 yenileme sonrası yeniden giriş yapmak zorunda kalır |
| Yetkilendirme Header Enjeksiyonu | Roller hedef servise taşınacak | Authorization sekmesi aktif, addRolesToHeader true, özel header adı set | Roller belirlenen header’a eklenir, hedef servis RBAC uygular |
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 JWT 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 → JWT 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_JWTAuth- 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: “Password grant ile LDAP üzerinden JWT üretir.” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: JWT Kimlik Doğrulama Parametreleri | - Managed From This Policy: Credentials yönetimini politika mı kontrol edecek? Secret Manager dışı entegrasyonlarda true seçilir.- Grant Type: CLIENT_CREDENTIALS veya PASSWORD seçin; seçim, kullanılabilir kimlik kaynaklarını belirler. - Kimlik Kaynağı: PASSWORD için Identity Role Group modalından LDAP/Database/API veya Secret Manager seçimi yapın. - Check Client IP Address: Secret Manager tabanlı yapılarda isteğin geldiği IP’yi doğrular. |
| Adım 4: Token ve Refresh Yapılandırması | - Token Never Expires: Süresiz token üretecekse açın, aksi halde süreyi ve birimini girin. - Refresh Token Allowed: Yenileme izni verilecekse açın, hak sayısı ve geçerlilik süresini tanımlayın. - JWT Signature Algorithm: RS256/RS384/RS512 arasından hedef sistem gereksinimine göre seçim yapın. |
| Adım 5: Header ve Yetkilendirme Ayarları | - Allow URL Parameters: Token’ın query parametresiyle gönderimini mümkün kılar; yalnızca güvenilir senaryolarda önerilir. - Clear Auth: Gelen Authorization header’ını temizler; eski JWT’nin sıfırlanması için kullanılır. - Add User/Roles to Header: Kullanıcı ve rol bilgisini özel header isimleriyle hedef servise gönderir. - Authorization Configuration: Rol bazlı gömme, method access ve JWT yenileme servisi gibi ileri seçenekleri açı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 kimlik kaynağı seçimi tamamlandı. 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 |
|---|---|
| Role Bazlı Header Enjeksiyonu | - Authorization sekmesinden addRolesToHeader seçeneğini açın.- Header adını belirleyin (örn. X-Authenticated-UserRoles).- Roller JWT claim’lerinden hedef servise taşınır. |
| JWT Regenerator Service Entegrasyonu | - Kimlik kaynağı olarak API seçildiğinde ikinci servis modalını açın. - JWT yenileyici servisi seçin ve kaydedin. - Password grant akışında refresh token kullanımıyla entegre çalışır. |
| Method Bazlı Yetkilendirme | - Authorization sekmesinde Method Access özelliğini aktif edin. - API method listelerini seçip rol eşleştirmesi yapın. - İstekler yöntem bazında 403 ile reddedilebilir. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Token Ömrü Yönetimi | Kötü: Varsayılan süreleri her ortamda kullanmak. İyi: Canlı Ortam için 15 dk, Geliştirme için 60 dk belirlemek. En İyi: Kullanım metriklerine göre token süresini düzenli gözden geçirmek. |
| Refresh Token Stratejisi | Kötü: Sınırsız yenileme hakkı tanımak. İyi: 3 yenileme hakkı ve 24 saatlik süre kullanmak. En İyi: MFA zorunlu oturumlarda refresh’i kapatmak. |
| Header Kullanımı | Kötü: Varsayılan header isimlerini değiştirmeden bırakmak. İyi: Hedef servisin beklediği header adlarını tanımlamak. En İyi: Güvenlik taramasından geçen özel header adları kullanmak. |
| Grant Type Seçimi | Kötü: Tüm istemcilerde PASSWORD grant kullanmak. İyi: Makine-makine iletişimde CLIENT_CREDENTIALS tercih etmek. En İyi: Minimum yetki prensibiyle grant seçimini per istemci analizine dayandırmak. |
| Kimlik Kaynağı Yönetimi | Kötü: Aynı anda birden fazla kimlik kaynağı tanımlamak. İyi: Her grant tipinde tek kaynak seçmek. En İyi: Secret Manager sürümleriyle uyumlu merkezi kimlik yönetimi kurmak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Token Saklama | Token’ları tarayıcı localStorage yerine Secure Cookie’de saklayın; HttpOnly ve Secure bayraklarını zorunlu tutun. |
| İmza Algoritması | RS256 dışına geçerken IM sertifika yönetiminin hazır olduğundan emin olun; anahtar rotasyonunu planlayın. |
| Refresh Token Koruması | Yenileme uç noktalarını IP ve cihaz doğrulamasıyla sınırlayın; başarısız girişimleri loglayın. |
| Header Hijacking Önlemleri | ClearAuth özelliğini legacy token geçişlerinde aktif edin; karışık kimlik doğrulama zincirleri oluşturmayın. |
| Audit ve İzleme | Politika loglarını SIEM’e aktarın; grant tipine göre başarısız girişleri ayrı dashboard’larda izleyin. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Sınırsız Token Ömrü | Neden kaçınılmalı: Güvenlik ihlallerinde kalıcı yetki sağlar. Alternatif: Token sürelerini ortam bazlı kısaltın. |
| URL Parametresiyle Token Taşıma | Neden kaçınılmalı: Loglarda token sızıntısına yol açar. Alternatif: Header veya Authorization Bearer kullanın. |
| Ortak Kimlik Kaynağı | Neden kaçınılmalı: Üretim ve test kimlikleri karışabilir. Alternatif: Her ortam için ayrı Secret Manager domaini kullanın. |
| Yetkisiz Refresh Servisi | Neden kaçınılmalı: Yenileme endpoint’i ele geçirilebilir. Alternatif: JWT Regenerator servisini sadece güvenli ağ segmentlerinden erişilebilir kılın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Token Hesaplama Süresi | Öneri: RS256 tercih edip anahtar boyutunu gereksiz büyütmeyin. Etki: JWT üretimi milisaniyeler seviyesinde kalır. |
| Refresh Çağrıları | Öneri: Yenileme sayısını sınırlayın, gereksiz round-trip’i azaltın. Etki: Gateway throughput’u artar. |
| Kimlik Kaynağı Yanıt Süresi | Öneri: LDAP/API kaynaklarını Cache ile destekleyin. Etki: Throttling tetiklenmeden yüksek TPS yönetilir. |
| Header Boyutu | Öneri: Rol listelerini minimal tutun, gereksiz claim aktarmayın. Etki: Upstream servilerine giden header yükü azalır. |
| Koşul Değerlendirmesi | Öneri: Query Builder kurallarını optimize edin; gereksiz regex kullanmayın. Etki: Politika değerlendirme süresi düşer. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Password grant kullanan politikada kimlik kaynağı olmadan kayıt yapabilir miyim? | Hayır. PASSWORD seçiliyken bir Identity Role Group veya Secret Manager bağlantısı zorunludur; aksi halde politika Validation hatası verir. |
| Genel | Token Never Expires seçeneği ne zaman kullanılır? | Sadece makine-makine iletişiminde ve güvenliği başka katmanların sağladığı durumlarda önerilir; kullanıcı tabanlı erişimlerde risklidir. |
| Teknik | JWT Regenerator Service API zorunlu mudur? | Sadece kimlik kaynağı API seçildiğinde ve refresh token senaryosunda gereklidir; diğer kaynaklarda otomatik olarak pasif kalır. |
| Teknik | Header’a eklenen rol listesi nasıl belirlenir? | Authorization Configuration alanında seçilen rol/claim eşleştirmeleri doğrultusunda addRolesToHeader aktifken otomatik yazılır. |
| Kullanım | Global politikayı local kopyaya dönüştürmek için ne yapmalıyım? | Detay sayfasından [Localize] butonunu kullanın; politika yeni bir local sürüme kopyalanır ve düzenlenebilir hale gelir. |
| Kullanım | Politika ismi çakışırsa nasıl ilerlerim? | Sistem name-exist kontrolüyle uyarır; ismi değiştirin veya global politikayı localize ederek benzersiz ad verin. |