Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) akışına giren JOSE/JWT tokenlarını doğrulayarak kimlik bilgilerinin güvenilirliğini garanti altına almak üzere tasarlanmıştır.
- Belirlenen issuer, audience ve claim kurallarını zorunlu tutarak yetkisiz erişimlerin önüne geçer ve hassas endpoint’lerin korunmasını sağlar.
- Şifrelenmiş JWE içeriklerini güvenli şekilde çözerek aşağı akış servislerine temizlenmiş veri aktarımı sunar.
- Kimlik ve rol bilgisini header seviyesinde yayarak downstream servislerde merkezi yetkilendirme politikaları ile entegre çalışır.
Ç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 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ı?
- JOSE İçeriği Çözümleme: Token belirlenen kaynaktan (body, Authorization header veya değişken) okunur; gerekiyorsa seçilen anahtar kaynağına (Gömülü JWK veya Dinamik HTTP) göre şifre çözümü yapılır ve claim seti doğrulamaya hazırlanır.
- Karar Verme:
- Eşleşme Var: İmza/şifreleme geçerli ise, claim ve audience kuralları sağlanırsa ve issuer ACL onaylanırsa istek akışa devam eder, gerekirse kullanıcı bilgisi header’a eklenir.
- Eşleşme Yok: Token çözülemezse, imza doğrulanamazsa, claim kuralları ihlal edilirse veya ACL reddi oluşursa istek politika tarafından sonlandırılır.
- 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; gövde (Gövde), Authorization başlığı (Authorization Başlığı) veya seçilen değişkenden (Değişkenden Seç) okunabilir; değişken senaryolarında değişken seçici ile atanır.
- İstemci Kaynağı (Client Source): Issuer/istemci bilgisinin okunacağı kaynak: Başlık, Claim’ler veya Değişken. Değişken seçiliyse Client Source Variable zorunlu; aksi halde Client Fieldname (JSON Path veya claim adı, örn.
iss) zorunludur. - Granüler Claim Doğrulaması: Accepted audience listesi, Exact Match Claim (anahtar-tür-değer), Required Claim ve Prohibited Claim listeleri ile çok katmanlı doğrulama kurgulanır.
- Kimlik ve Rol Yayılımı: İstekten çıkarılan kullanıcı kimliği Add User to Header ile header’a eklenebilir (User Header Name zorunlu); merkezi yetki kontrolü desteklenir.
- 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
- Anahtar Kaynağı Modu (Key Source Mode): İmza doğrulama ve şifre çözme için anahtar Gömülü (Secret Manager’daki JWK) veya Dinamik HTTP (HTTP isteği ile uzaktan anahtar çekme) olarak seçilebilir.
- Dinamik Anahtar Çekme (Dynamic Key Fetching): Dinamik HTTP seçildiğinde HTTP İstek Yapılandırması (Test Console), Anahtar Çıkarma Değişkeni (Key Extraction Variable), Anahtar Formatı, Anahtar Algoritması, Kid (Key ID), önbellek ayarları (Uygula Kriteri, Kapasite, TTL, Önbellek Depolama Tipi, Cache Geçersiz Kılma Başlıklarına Uy, Bağlantı Zaman Aşımı, Cache Hata İşleme Tipi), Anahtar Hatasında Tekrar Dene, Doğrulama Hatasında Cache’i Geçersiz Kıl ve Yanıtı Ayrıştır (Try It) butonu ile test edilebilir.
- JWK Yaşam Döngüsü Yönetimi: Gömülü modda imza ve şifreleme anahtarları Secret Manager üzerinden seçilir veya yeni anahtar oluşturulur; gerekli roller yeni anahtar tanımlayabilir.
- Issuer ACL ve IP Kontrolü: Validate ACL for Issuer ile issuer bazlı izin listesi; Check Client IP Address ile isteği yapan istemci IP doğrulaması (politika listesi türü ve validateACLforIssuer açıkken görünür).
- Claim Decode ve Yeniden Yazma: Strip and Decode (Yok, Tümü, Kısmi) ile JWT/JWE payload’u yalıtılıp decode edilebilir; PARTIAL ise Decode Edilecek Claim (jwtClaimsToDecode) zorunlu. Decoded Claims Target (Gövde, Authorization Başlığı, Değişkenden Seç) ve gerekirse Decoded Claims Target Variable ile çıktı yönlendirilir.
- Yetkilendirme Yapılandırması: Politika listesi türü Request, politika global değil ve Validate ACL for Issuer açıkken Authorization Configuration bileşeni görünür; rol bazlı erişim ve method access yapılandırılır.
- Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Geliştirme, Test, Canlı Ortam) 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 JWT Doğrulama | Mobil uygulama Authorization header’da JWT taşır | joseTarget=Authorization Başlığı, validateSign=true, issuer JWKS veya Embedded JWK kullan | Geçerli token kabul edilir, hatalı imzalar 401 döndürür |
| IoT JWE Çözümü | IoT cihazları şifreli payload gönderir | decrypt=true, decryptByIssuer=false, Key Source Mode ile Gömülü veya Dinamik HTTP, encryption JWK seç | Payload çözülür, içerik downstream servislere aktarılır |
| Issuer Beyaz Listeleme | Belirli issuer değerleri dışında erişim istenmez | clientSourcePart=CLAIMS, clientFieldname=iss, exact match map ile liste | Uyumsuz issuer istekleri 403 ile engellenir |
| Audience Segmentasyonu | Mikroservisler farklı audience bekler | acceptedAudienceList ortam bazlı doldur | Yanlış audience içeren istekler özelleştirilmiş hata alır |
| Kullanıcı Header Enjeksiyonu | Downstream servisler kimlik header’ı ister | addUserToHeader=true, userHeaderName=X-Authenticated-UserId | Kimlik bilgisi güvenli şekilde başlıkta iletilir |
| Yetkilendirme Entegrasyonu | Rol bazlı erişim denetimi gerekir | enableAuthorization=true, Authorization Configuration bileşeninde method access yapılandır | İstek, rol eşleşmesi sağlanmazsa politika tarafından durdurulur |
| Uzaktan Anahtar ile Doğrulama/Şifre Çözme | Anahtar bir HTTP endpoint’ten alınacak | Key Source Mode = DYNAMIC_HTTP, HTTP Request ve Key Extraction Variable tanımlanır, Try It ile test edilir | Çalışma anında anahtar uzaktan çekilir ve cache’lenebilir |
| Policy Group Senkronizasyonu (opsiyonel) | Aynı kurallar çoklu API Proxy’de kullanılacak | Global politika oluştur, Policy Group’a ekle | Tek değişiklikle tüm API Proxy’lerde politika güncellenir |
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 (hangi kaynaktan token okunacağı, claim/audience kuralları, imza/şifre çözme kaynağı, ACL ve yetkilendirme vb.) doğrudan etkiler. Bu sayede politika hem kuruma özel gereksinimlere göre özelleştirilebilir hem de merkezi olarak yönetilebilir.Yeni JOSE 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 → JOSE Doğrulama Politikası bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın. |
| Adım 2: Temel Bilgileri Girme (Definition sekmesi) | Policy Status (Politika Durumu): Aktif veya Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Toggle ile değiştirilebilir. Name (Ad) — Zorunlu: Örnek: Production_JOSEValidation. Benzersiz isim girin; boşlukla başlamaz; max 255 karakter. Sistem otomatik kontrol eder: yeşil tik = kullanılabilir, kırmızı çarpı = mevcut isim.Description (Açıklama): Örnek: “JWT imza ve şifreleme doğrulaması yapar.” Maks. 1000 karakter; politikanın amacını açıklar. |
| Adım 3: Politika Yapılandırması — JOSE Kaynağı ve İstemci Bilgisi | JOSE Target (Doğrulama/Şifre Çözme için Hedef) — Zorunlu: Token’ın nereden okunacağını belirler. Gövde = istek gövdesinden, Authorization Başlığı = Authorization header’ından, Değişkenden Seç = bir proje değişkeninden okunur. Kullanım senaryonuza göre birini seçin; örn. çoğu JWT Authorization: Bearer <token> ile gelir, bu durumda Authorization Başlığı seçilir.JOSE Target Variable — Koşullu (sadece Hedef = Değişkenden Seç iken): Token değerinin tutulduğu proje değişkenini işaret eder; politika çalışırken token bu değişkenden okunur. Başka bir politika veya akış önceden token’ı bu değişkene yazmış olmalıdır. Değişken Seç ile proje değişkeni atayın; Güncelle ile değişken tanımını düzenleyebilirsiniz. Client Source Part — Zorunlu: Issuer/istemci kimliğinin nereden alınacağını seçersiniz: Başlık = HTTP header’dan, Claim’ler = JWT içindeki claim’den, Değişken = proje değişkeninden. Multi-tenant’ta genelde Claim’ler ve iss kullanılır.Client Source Variable — Koşullu (sadece Client Source Part = Değişken iken): Issuer bilgisinin hangi değişkenden okunacağını belirtir. Bu değişkenin değeri (örn. issuer URL’si) ACL ve anahtar eşleştirmede kullanılır. Proje değişkeni seçin. Client Fieldname — Koşullu (Client Source Part = Başlık veya Claim’ler iken): Issuer bilgisinin hangi alan adıyla okunacağını tanımlar. JWT kullanıyorsanız genelde iss yazın; token’daki iss claim’i okunur. Header’dan okuyacaksanız header adını (örn. X-Tenant-Id) veya JSON Path (örn. $.header.tenant_id) girebilirsiniz. Bu değer, doğrulama ve issuer bazlı anahtar/ACL seçiminde kullanılır. |
| Adım 4: Claim Doğrulama Ayarları (Claim paneli) | Accepted Audience List: Token’daki aud claim’inin bu listedeki değerlerden en az biriyle eşleşmesini zorunlu kılar; eşleşmezse doğrulama başarısız olur. Metin kutusuna örn. https://api.sizin-alan.com yazıp onaylayın; chip olarak eklenir. Birden fazla audience ekleyebilirsiniz. Boş bırakırsanız audience kontrolü yapılmaz.Exact Match Claim Map: Belirli claim adları için tam eşleşme (anahtar + tip + değer) zorunlu kılar; token’da bu claim’ler aynı değerde olmalıdır. + ile satır ekleyin; Key = claim adı (örn. role), Value Type = STRING/NUMBER/BOOLEAN vb., Value = beklenen değer. İstekte bu claim yoksa veya değer farklıysa doğrulama reddedilir.Required Claim List: Bu listedeki claim’lerin token’da mutlaka bulunmasını ister; yoksa doğrulama başarısız olur. Değer kontrolü yapılmaz, sadece varlık kontrolü. Claim adını yazıp ekleyin (örn. sub, email).Prohibited Claim List: Bu listedeki claim’ler token’da bulunmamalıdır; bulunursa doğrulama reddedilir. Güvenlik veya şema kısıtı için kullanılır. Yasaklamak istediğiniz claim adlarını chip olarak ekleyin. |
| Adım 5: JWE Şifre Çözme Ayarları (Decrypt paneli) | Decrypt (Şifre Çöz): Toggle; JWE şifre çözme açılır/kapanır. Decrypt by Issuer (İstemci JWK’sı ile Şifre Çöz): Toggle; sadece Decrypt açıkken görünür; issuer tarafında şifre çözme kullanılır. Aşağıdaki alanlar sadece Decrypt açık ve Decrypt by Issuer kapalı iken görünür: Key Source Mode (Anahtar Kaynağı Modu) — Zorunlu: Gömülü veya Dinamik HTTP. — Gömülü seçiliyse: • Şifre Çözme için JWK (jwkIdForDecryptionAndEncryption) — Zorunlu: Açılır liste (Secret Manager’daki şifreleme JWK’ları), Temizle ve Yeni butonları. Seçilen JWK tabloda gösterilir. — Dinamik HTTP seçiliyse: HTTP İstek Yapılandırması: Anahtarın alınacağı URL ve istek; Test Console’da girin (URL zorunlu). Key Extraction Variable: HTTP yanıtından anahtarın nereden çıkarılacağını tanımlayan proje değişkeni; değişkende JSONPath (örn. $.keys[0]) ile yanıt gövdesindeki anahtar alanı işaret edilir. Çalışma anında yanıt bu ifadeyle işlenir, çıkan veri anahtar olarak kullanılır. Key Format / Key Algorithm: Yanıt formatı ve algoritma; NONE + Try It ile otomatik algılanabilir. Kid (Key ID) — İsteğe bağlı: JWKS/yanıtta birden fazla anahtar varsa hangisinin kullanılacağını belirtir. Enable Cache ve Apply By: Önbellek açıksa Apply By ile önbellek hangi değere göre anahtarlanır (örn. issuer değişkeni); aynı değer için anahtar tekrar çekilmez. Yanıtı Ayrıştır (Try It): Kaydetmeden test; başarılıysa format/algoritma otomatik atanır (aşağıda Try It bölümüne bakın). |
| Adım 6: JWS Doğrulama Ayarları (Validation paneli) | Validate Expiration Time: Açıksa token’daki exp kontrol edilir; süresi geçmişse doğrulama reddedilir.Validate Sign: İmza doğrulama aç/kapat. Açıksa JWS imzası doğrulanır; anahtar Gömülü JWK veya Dinamik HTTP’den alınır (Validate by Issuer kapalıysa). Validate by Issuer: Açıksa anahtar issuer’ın JWKS endpoint’inden alınır; kapalıysa sizin tanımladığınız anahtar kaynağı kullanılır. Key Source Mode (Validate Sign açık, Validate by Issuer kapalı iken): Gömülü veya Dinamik HTTP — imza doğrulama anahtarının nereden geleceğini seçersiniz. — Gömülü: Doğrulama için JWK ile Secret Manager’dan imza JWK seçin. Her gelen imzalı token bu anahtarla doğrulanır. — Dinamik HTTP: Adım 5’teki ile aynı mantık: HTTP İstek Yapılandırması (URL zorunlu), Key Extraction Variable (yanıttan anahtar çıkaran değişken; JSONPath ile alan işaret edilir), Key Format (yanıt formatı), Key Algorithm (NONE + Try It ile otomatik algılanabilir), Kid (çoklu anahtar varsa hangisi), Enable Cache ve Apply By (önbellek hangi değere göre; örn. issuer değişkeni). Yanıtı Ayrıştır (Try It) ile kaydetmeden test edebilirsiniz. |
| Adım 7: ACL Ayarları (Authentication paneli) | Add User to Header: Doğrulama sonrası kullanıcı kimliği bir HTTP header’a yazılır. Toggle; doğrulama sonrası kullanıcı kimliği header’a eklenir. User Header Name: Kimliğin ekleneceği header adı; örn. X-Authenticated-UserId. Sadece Add User to Header açıkken zorunludur.Validate ACL for Issuer: Issuer bazlı erişim listesi (ACL) kontrolü; issuer izin listesinde yoksa istek reddedilir. Check Client IP Address: İstemci IP’sinin ACL’deki IP listesiyle uyumlu olmasını zorunlu kılar. Sadece politika listesi türü Request ve Validate ACL for Issuer açıkken görünür. |
| Adım 8: Data Manipülasyonu (Data Manipülasyonu paneli) | Strip and Decode (JWT/JWE Payload’u Yalıt ve Decode Et): Yok, Tümü veya Kısmi. Yok ise decode/yönlendirme yok; Tümü veya Kısmi ise aşağıdaki alanlar kullanılır. JWT Claims to Decode (Decode Edilecek Claim) — Koşullu, zorunlu: Sadece Strip and Decode = Kısmi iken görünür; bu modda yalnızca belirttiğiniz claim decode edilir. Decode edilecek claim adı (örn. data).Decoded Claims Target (Target for Decoded Claims) — Koşullu, zorunlu: Sadece Strip and Decode ≠ Yok iken görünür. Gövde, Authorization Başlığı veya Değişkenden Seç. Decoded Claims Target Variable — Koşullu, zorunlu: Sadece Strip and Decode ≠ Yok ve Target = Değişkenden Seç iken görünür; decode edilmiş claim’ler bu değişkende saklanır. Decode edilmiş claim’lerin yazılacağı proje değişkeni. |
| Adım 9: Yetkilendirme Yapılandırması — Koşullu | Sadece politika listesi türü Request, politika global değil ve Validate ACL for Issuer açıkken Authorization Configuration bileşeni görünür. Rol bazlı erişim, method access ve yetkilendirme servisi ayarları bu bileşenden yapılır. |
| Adım 10: Koşul Tanımlama (Condition sekmesi) — İsteğe bağlı | Condition sekmesine geçin. Query Builder ile koşul kuralları tanımlayın. Örnekler: Ortam bazlı Header = X-Environment, Equals, production; API Key Header = X-API-Key, Starts With = PROD-; Endpoint Path = /api/admin/*. Koşul tanımlanmazsa politika her zaman uygulanır. |
| Adım 11: Hata Mesajı Özelleştirme (Error Message Customization sekmesi) — İsteğe bağlı | Error Message Customization sekmesine gidin. Erişim reddedildiğinde dönecek HTTP durum kodu ve mesajı özelleştirin. Varsayılan: { "statusCode": 403, "message": "[Default hata mesajı]" }. Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" }. |
| Adım 12: Kaydetme | Sağ üstteki [Save] butonuna tıklayın. Kontrol listesi: Benzersiz isim; JOSE Target ve (Değişkenden Seç ise) JOSE Target Variable; Client Source Part; (Değişken ise) Client Source Variable, (değilse) Client Fieldname; Add User to Header ise User Header Name; Strip and Decode ≠ Yok ise Decoded Claims Target ve (Değişkenden Seç ise) Decoded Claims Target Variable; Validate Sign açıksa ve Validate by Issuer kapalıysa Key Source Mode’a göre JWK veya Dinamik HTTP (URL, Key Extraction Variable, Key Format); Decrypt açıksa ve Decrypt by Issuer kapalıysa aynı JWK/Dynamic HTTP kuralları. 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 JWK Entegrasyonu (Embedded) | İmza veya şifreleme panelinde Key Source Mode = Gömülü iken ilgili JWK seçicisini açın. Var olan anahtarı seçin veya New ile Secret Manager’a gidin. Kaydedilen JWK değişiklikleri politika ile otomatik eşleştirilir. |
| Dynamic HTTP ile Anahtar Çekme | Key Source Mode = DYNAMIC_HTTP seçin. HTTP İstek Yapılandırması (Test Console) ile URL ve istek, Key Extraction Variable (zorunlu), Key Format, Key Algorithm belirleyin; cache açacaksanız Apply By, Capacity, TTL ve diğer cache alanlarını doldurun. Yanıtı Ayrıştır (Try It) ile test edin; başarılıysa algılanan format/algoritma otomatik atanabilir. |
| Issuer ACL ve IP Doğrulaması | Validate ACL for Issuer’ı etkinleştirin. Issuer bazlı ACL kurallarını güvenlik servisi üzerinden güncelleyin. Politika listesi Request ve validateACLforIssuer açıkken Check Client IP Address ile gelen isteğin IP’sini doğrulayın. |
| Claim Decode & Rewrite | Strip and Decode’u ALL veya PARTIAL yapın. PARTIAL ise Decode Edilecek Claim (jwtClaimsToDecode) girin. Decoded Claims Target ile çıktıyı BODY, header veya değişkene yönlendirin; CHOOSE_FROM_VARIABLE ise Decoded Claims Target Variable atayın. Diğer politikalarında aynı değişkeni kullanın. |
| Yetkilendirme Yapılandırması | Politika Request türünde, global değil ve Validate ACL for Issuer açıkken görünen Authorization Configuration bileşeninde enableAuthorization, addRolesToHeader, rolesHeaderName ve method access ayarlarını yapılandırın. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Audience Yönetimi | Kötü: Accepted audience boş bırakmak. İyi: Her mikroservis için ayrı audience değeri tanımlamak. En İyi: Ortam bazlı audience listelerini (Geliştirme/Test/Canlı Ortam) ayrı politikalarla yönetmek. |
| İmza Doğrulama | Kötü: validateSign kapalı çalıştırmak.İyi: Issuer JWKS endpoint’ini validateByIssuer ile kullanmak veya Gömülü JWK seçmek.En İyi: Issuer olmayan senaryolarda merkezi JWK kasasını veya Dynamic HTTP cache’i zorunlu kılmak. |
| Şifreleme Yönetimi | Kötü: Şifreli tokenlarda decrypt kapalı bırakmak.İyi: Decrypt by Issuer veya Gömülü JWK ile çözümlemeyi etkinleştirmek. En İyi: Her issuer için ayrı encryption anahtarı tanımlayıp periyodik anahtar döndürmek; Dynamic HTTP’de Try It ve cache kullanmak. |
| Claim Politikaları | Kötü: Claim listelerini tanımsız bırakmak. İyi: Required ve Prohibited claim listelerini belirlemek. En İyi: Exact Match Claim haritası ile değer-tip doğrulaması yapmak. |
| Header Entegrasyonu | Kötü: Kullanıcı kimliğini downstream servislere iletmemek. İyi: addUserToHeader ile kimlik header’ı eklemek.En İyi: Rol header’larını güvenlik log’larıyla eşleyip denetlemek. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Anahtar Yönetimi | Embedded modda JWK’ları Secret Manager’da saklayın; Dynamic HTTP’de endpoint güvenliği ve cache erişim kısıtları önemlidir. |
| Issuer Güveni | Issuer whitelist’ini düzenli güncelleyin; şüpheli issuer’ları derhal kaldırın. |
| Token Ömrü | validateExpirationTime daima açık olmalı; uzun süreli tokenları kısıtlayın. |
| Header Sertliği | Eklenen kimlik/rol header’larını yalnızca HTTPS üzerinden iletin; loglarda maskelenmesini sağlayın. |
| Hata Mesajları | Hata mesajlarında içsel detay paylaşmayın; generik mesaj + hata kodu kombinasyonu kullanın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Statik Gömülü JWK | Neden kaçınılmalı: Kod içine gömülen anahtarlar sızıntıya açıktır. Alternatif: Secret Manager (Gömülü) veya Dinamik HTTP ile güvenli anahtar tedariki kullanın. |
| Belirsiz Claim Kuralları | Neden kaçınılmalı: Tüm claim’leri kabul etmek güvenlik açığı yaratır. Alternatif: Required ve Prohibited listelerini tanımlayın. |
| Decode Edilmeyen Şifreli Veri | Neden kaçınılmalı: Şifreli veri doğrulanmadan geçer. Alternatif: decrypt ayarını zorunlu tutup uygun JWK veya Dynamic HTTP’yi bağlayın. |
| İzlenmeyen Header Ekleri | Neden kaçınılmalı: Denetlenmeyen header’lar kötüye kullanılabilir. Alternatif: Header kullanımını loglayın ve erişim kontrolü uygulayın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| JWK Önbelleği | Sık kullanılan JWK’leri Secret Manager cache’i (Gömülü) veya Dinamik HTTP Enable Cache ile paylaşın. İmza doğrulama süresi düşer. |
| Claim Kuralı Sayısı | Gereksiz claim kontrollerini temizleyin. Politika yürütme süresi kısalır. |
| Decode Seçenekleri | Yalnızca ihtiyaç duyulan claim’leri decode edin (PARTIAL + jwtClaimsToDecode). Bellek ve CPU tüketimi azalır. |
| Global vs Local Kullanım | Aynı kuralları paylaşan API’lerde global politika tercih edin. Yönetim ve deploy süreleri kısalır. |
| Koşul Sadeleştirme | Query Builder’da gereksiz koşulları kaldırın. İstek başına koşul değerlendirme süresi azalır. |
| Dynamic HTTP Cache | Enable Cache açık, Capacity ve TTL uygun değerlerde olsun. Uzak anahtar tekrarlı çekilmez; gecikme azalır. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Politika hangi token türlerini doğrular? | JOSE standartlarını (JWS/JWE) destekler; JSON Web Signature/Encryption kurallarına göre doğrulama yapar. |
| Genel | Politika birden fazla API Proxy için paylaşılabilir mi? | Evet, global tanımlandıysa Policy Group aracılığıyla birden fazla API Proxy ile paylaşılır. |
| Teknik | Issuer kendi JWKS endpoint’ini sunuyorsa nasıl yapılandırılır? | Validate by Issuer (İstemci JWK’sı ile Doğrula) seçeneğini etkinleştirerek gateway’in issuer JWKS’inden anahtar almasını sağlayın. |
| Teknik | Şifrelenmiş JWE içeriği nasıl çözümlenir? | Decrypt seçeneğini açın; Decrypt by Issuer kapalıysa Key Source Mode ile Embedded (JWK seçin) veya Dinamik HTTP (URL, Key Extraction Variable, Key Format, Key Algorithm ve isteğe bağlı cache) yapılandırın. Çözülen payload belirlenen hedefe yazılır. |
| Teknik | Dynamic HTTP ile anahtar nasıl kullanılır? | Key Source Mode = Dinamik HTTP seçin; HTTP İstek Yapılandırması (Test Console), Key Extraction Variable (zorunlu), Key Format, Key Algorithm tanımlayın. Yanıtı Ayrıştır (Try It) ile test edin. |
| Kullanım | Kullanıcı kimliğini header’a eklemek güvenli midir? | HTTPS üzerinde iletin, header adını (User Header Name) maskeyin ve sadece yetkili servislerin okumasına izin verin. |
| Kullanım | Claim kurallarını ortam bazında nasıl ayırabilirim? | Her ortam için ayrı politika kopyası oluşturun veya Condition sekmesinde ortam header’ına göre koşul tanımlayın. |
| Kullanım | Check Client IP Address ne zaman görünür? | Politika listesi türü Request ve Validate ACL for Issuer açıkken ACL Ayarları panelinde bu toggle görünür. |