Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) yanıt veya isteğini JOSE standartlarına uygun biçimde JWT olarak yeniden paketleyerek tüketici entegrasyonlarını basitleştirmek.
- Uygulama servisleri arasında taşınan claim verilerini imza ve şifreleme katmanları ile güvence altına almak.
- JWK kasası ile entegre çalışarak anahtar yönetiminin merkezi ve denetlenebilir biçimde sürdürülmesini sağlamak.
- Koşul motoru desteğiyle belirli endpoint, header ya da ortam kombinasyonlarında dinamik olarak tetiklenmek.
- Ek claim haritası ve veri manipülasyonu hedefleri sayesinde kurumlara özgü token zenginleştirmelerini kod değişikliği olmadan yönetmek.
Ç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ü: JOSE Uygulama 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ı?
- Token Üretim ve Güvenlik Katmanı: Hedef alan belirlendikten sonra claim seti toplanır, ek claim haritası eklenir, JWK seçimine göre imzalama ve isteğe bağlı şifreleme uygulanır.
- Karar Verme:
- Eşleşme Var: Üretilen JWT belirtilen hedefe (gövde, Authorization header veya değişken) yazılır ve trafik devam eder.
- Eşleşme Yok: Politika devre dışı kalır, istek orijinal içeriğiyle iletilir.
- 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
- Esnek JOSE Hedefi: Token üretim çıktısı gövde, Authorization header veya seçilen değişkende saklanabilir; yanıt manipülasyonlarını kolaylaştırır.
- Hazır Claim Anahtarları: Issuer, Subject, Audience, Expiration gibi çekirdek claim alanları anahtar/kilit kombinasyonlarıyla yönetilir.
- Ek Claim Haritası: Tür kontrollü MapValue desteğiyle metin, liste veya sayısal claim’ler arayüzden eklenip düzenlenebilir.
- 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
- JWK Yönetim Entegrasyonu: Secret Manager üzerinden JWK arama, seçim, güncelleme ve yeni anahtar üretimi tek tıklamayla yapılır.
- Çift Katmanlı Güvenlik: Aynı istekte imza ve şifreleme kombinasyonu uygulanarak token bütünlüğü ve gizliliği eşzamanlı sağlanır.
- Veri Manipülasyonu Senkronizasyonu: Kodlanmış claim hedefi ve decode sonrası değişken ataması ile zincir politikalar arasında veri paylaşımı yapılır.
- 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ç |
|---|---|---|---|
| Mikroservis Yanıtını JWT’ye Dönüştürme | Servis düz metin JSON döndürüyor, tüketici JWT bekliyor | joseTarget=BODY, hazır claim’ler aktif, imza açık | Yanıt JWT formatında döner, tüketici ek iş yapmaz |
| Header Üzerinden JWT Taşıma | Mobil istemci Authorization header’ında imzalı token istiyor | joseTarget=AUTHORIZATION_HEADER, addTypeToHeader=true | Token Authorization: JWT <token> olarak eklenir |
| Çoklu Audience Yönetimi | Aynı API farklı hedef sistemlere token iletiyor | addAudience=true, audience listesine çoklu değer eklenir | Token aud claim’i çoklu değer içerir |
| İç Sistem Anahtarıyla İmza | Issuer tarafında imzalanmış token tercih ediliyor | sign=true, signByIssuer=true seçilir | Gateway imza anahtarı istemez, issuer imzası korunur |
| Çift Katmanlı Güvenlik | Dış entegrasyon imza+şifreleme kombinasyonu zorunlu kılıyor | sign=true, encrypt=true, uygun JWK’lar seçilir | Token önce imzalanır sonra seçilen yöntemle şifrelenir |
| Veri Manipülasyonu Zinciri | Sonraki politika decode edilmiş claim’lere ihtiyaç duyuyor | encodedClaimsTargetForDataManipulation=BODY, decoded değişken atanır | Decode edilmiş claim’ler tanımlanan değişkende saklanı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 JOSE Uygulama 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 → JOSE Uygulama 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_JOSE- 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: “Çıkış gövdesini imzalı JWT’ye dönüştürür” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: JOSE Hedefi ve Claim Ayarları | - JOSE Target alanından gövde, Authorization header veya değişken seçin.- Değişken kullanacaksanız Variable seçiciden bir proje değişkeni atayın. - Claim panelinde addIssuer, addSubject, addAudience, addExpirationTime seçeneklerini gereksinime göre açın ve zorunlu alanları doldurun.- Additional Claim Map tablosundan tür bazlı claim ekleyerek payload’ı zenginleştirin. |
| Adım 4: İmza Konfigürasyonu (Varsa) | - Sign anahtarını aktifleştirerek token imzasını açın.- Issuer tarafından imza sağlanacaksa Sign by Issuer seçeneğini kullanın.- Gateway imzalayacaksa Secret Manager listesinden jwkIdForValidationAndSign alanını seçin veya yeni anahtar oluşturun. |
| Adım 5: Şifreleme ve Veri Manipülasyonu (Varsa) | - Gizlilik gerekiyorsa Encrypt anahtarını aktifleştirin ve Encryption Method seçin.- Issuer tarafında şifreleme yapılacaksa Encrypt by Issuer seçeneğini açın, aksi halde JWK seçin.- Encoded Claims Target for Data Manipulation alanından token’ın saklanacağı hedefi belirleyin, değişken gerekiyorsa ilgili variable’ı seçin. |
| 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 tanımlı JOSE hedefi ve gerekli JWK seçimleri mevcut 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 |
|---|---|
| Dinamik Claim Haritalama | - Additional Claim Map tablosundan + butonuna basın.- Claim anahtarını ve uygun valueType bilgisini seçin.- Değer alanını doldurup kaydedin; değişiklik anında listeye yansır. |
| Çift Rol JWK Yönetimi | - İmza veya şifreleme panelinden ilgili JWK seçicisini açın. - Var olan anahtarı seçin veya New seçeneğiyle Secret Manager’a yönlenin. - Güncel JWK kaydedildiğinde politika formu otomatik güncellenir. |
| Token Zinciri Manipülasyonu | - Encoded Claims Target alanından token’ın yazılacağı hedefi seçin.- Decode edilmiş veriyi başka politikaya aktaracaksanız target değişkenini tanımlayın. - İlgili ikinci politikada aynı değişkeni kaynak olarak kullanarak veri akışını tamamlayın. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Claim Tasarımı | Kötü: Gereksiz tüm alanları claim olarak eklemek. İyi: Sadece işlevsel claim’leri tanımlamak. En İyi: Düzenli claim denetimleri ile minimal ama yeterli seti sürdürmek. |
| JWK Yönetimi | Kötü: Süresi dolmuş anahtarları kullanmaya devam etmek. İyi: JWK rotasyonunu manuel aralıklarla yapmak. En İyi: Secret Manager üzerinden otomatik rotasyon takvimi kurgulamak. |
| İmza ve Şifreleme Kombinasyonu | Kötü: Aynı token’a gereksiz yere hem imza hem şifreleme eklemek. İyi: Güvenlik gereksinimine göre sadece biriyle yetinmek. En İyi: Hassas veride önce imza sonra şifreleme uygulayarak tam güvenlik sağlamak. |
| Veri Manipülasyonu | Kötü: Decode edilmiş veriyi boş isimli değişkenlere yazmak. İyi: Anlamlı değişken isimleri kullanmak. En İyi: Politikalar arası veri akışını belgelemek ve standart isimler belirlemek. |
| Hata Mesajı Stratejisi | Kötü: Varsayılan hata mesajını tüm ortamda bırakmak. İyi: Ortam bazlı özel mesajlar hazırlamak. En İyi: Hata mesajlarında izlenebilirlik için referans kodları bulundurmak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Anahtar Saklama | JWK’ları sadece Secret Manager içerisinde tutun, dışa aktarımları şifreli kanallarla yapın. |
| Token Yaşam Süresi | Expiration değerlerini kısa tutun, Sliding veya Refresh token mekanizmaları kurun. |
| Issuer ve Audience Doğruluğu | issuer ve audienceList değerlerini kurumsal naming standardına göre belirleyip revizyonlarda güncelleyin. |
| Ek Claim Hijyeni | Ek claim’lerde kişisel veri varsa şifreleme zorunlu hale getirin ve veri minimizasyonu uygulayın. |
| İmza Anahtarı Yetkileri | JWK düzenleme yetkisini ROLE_API_SECURITY ile sınırlandırın, audit loglarını takip edin. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Tutarsız Claim Yapısı | Neden kaçınılmalı: Şema dışı claim’ler tüketici tarafında parse hatasına yol açar. Alternatif: Claim değişikliklerini sürüm kontrollü olarak devreye alın. |
| Yanlış JWK Eşlemesi | Neden kaçınılmalı: Eksik veya farklı algoritmaya sahip JWK seçimi token doğrulamasını bozar. Alternatif: İlgili algoritma için filtrelenmiş JWK listesini kullanın. |
| Sonsuz Token Süresi | Neden kaçınılmalı: Güvenlik ihlali durumunda token iptali mümkün olmaz. Alternatif: Kısa süreli token ve revocation list tasarlayın. |
| Hedef Alan Uyumsuzluğu | Neden kaçınılmalı: Yanıt gövdesi yerine header’a yazılan token tüketilmeyebilir. Alternatif: Entegrasyon dökümanı doğrultusunda hedef alanı netleştirin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Token Boyutu | Öneri: Gereksiz claim’leri kaldırın ve JSON minimal formatta tutun. Etki: Gönderim süresi ve bant genişliği düşer. |
| Şifreleme Metodu | Öneri: Donanım desteği olan algoritmaları (örn. A256GCM) tercih edin. Etki: CPU kullanımı azalır, gecikme düşer. |
| Ek Claim Sayısı | Öneri: MapValue tablosunda sadece gerekli claim’leri tanımlayın. Etki: Token boyutu küçülür, doğrulama süresi kısalır. |
| Koşul Motoru | Öneri: Query Builder’da gereksiz nested koşullardan kaçının. Etki: Politika değerlendirme süreci hızlanır. |
| JWK Lookup | Öneri: Sık kullanılan JWK’ları cacheleyen Secret Manager seçeneklerini aktif edin. Etki: İmza/şifreleme sırasında I/O gecikmeleri azalır. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | JOSE Uygulama Politikası hangi durumlarda kullanılır? | Token üretimi, claim yönetimi ve güvenli iletim gerektiren entegrasyonlarda kullanılır; özellikle tüketicinin JWT beklediği senaryolarda etkilidir. |
| Genel | İmza ve şifrelemeyi aynı anda açmak zorunlu mu? | Hayır, gereksinime göre sadece imza veya sadece şifreleme kullanılabilir; her ikisi birden hassas veriler için önerilir. |
| Teknik | JWK seçimi nasıl yapılır? | Secret Manager JWK listesi açılır; uygun algoritma ve amaçla eşleşen anahtar seçilir veya yeni anahtar oluşturulur. |
| Teknik | Değişkenden hedef seçince ne olur? | Politika token’ı belirtilen proje değişkenine yazar; başka politikalar veya backend bu değişkeni okuyabilir. |
| Kullanım | Audience listesine nasıl değer eklenir? | Add Audience aktif edilerek giriş kutusuna değer yazılır ve onaylanır; her değer chip olarak listelenir. |
| Kullanım | Hata mesajını özelleştirmek zorunda mıyım? | Zorunlu değil; ancak tüketici tarafı için yönlendirici bilgi gerekiyorsa Error Message sekmesinde özelleştirme yapılabilir. |