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, imza ve isteğe bağlı şifreleme için anahtar kaynağı (Embedded JWK veya Dynamic HTTP) seçimine göre işlem uygulanır.
- Karar Verme:
- Eşleşme Var: Üretilen JWT belirtilen hedefe (gövde, Authorization header, değişken veya Boş) 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 (Gövde), Authorization başlığı (Authorization Başlığı), seçilen değişken (Değişkenden Seç) veya boş hedef (Boş) olarak ayarlanabilir; yanıt manipülasyonlarını kolaylaştırır.
- JWT Claims Claim ve Escape JSON String: Hedef Boş değilse, ham verinin hangi claim adıyla payload’a yazılacağı (jwtClaimsClaim) ve JSON string’in escape edilip edilmeyeceği (escapeJsonString) ayarlanabilir.
- Hazır Claim Anahtarları: Issuer, Subject, Audience, Expiration, Issue Time, JWT ID ve Type (header’a tip bilgisi ekleme) 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
- Anahtar Kaynağı Modu (Key Source Mode): İmza ve şifreleme 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 isteği (Test Console), Anahtar Çıkarma Değişkeni (Key Extraction Variable), Anahtar Formatı (Otomatik Algıla, Genel Anahtar, Özel Anahtar, Sertifika, JWK JSON), Anahtar Algoritması, Kid (isteğe bağlı), önbellek ayarları (Uygula Kriteri değişkeni, Kapasite, TTL, Önbellek Depolama Tipi, Cache Geçersiz Kılma Başlıklarına Uy, Bağlantı Zaman Aşımı, Hata İşleme Tipi), Anahtar Hatasında Tekrar Dene, Doğrulama Hatasında Cache’i Geçersiz Kıl ve Try It (Yanıtı Ayrıştır) butonu ile test edilebilir.
- JWK Yönetim Entegrasyonu: Gömülü modda 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: Oluşturulan JWT/JWE için Injection Target (encoded claims target) ve decode sonrası değişken ataması (decoded claims target variable) 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, typeValue=JWT | 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 veya Dynamic HTTP 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 ile token’ın yazılacağı hedef, decoded claims için değişken atanır | Decode edilmiş claim’ler tanımlanan değişkende saklanır |
| Uzaktan Anahtar ile İmza/Şifreleme | Anahtar bir HTTP endpoint’ten alınacak | Key Source Mode = Dinamik 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 |
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 hedefe token yazılacağı, koşullu aktivasyonlar, imza/şifreleme kaynağı 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 (Definition sekmesi) | Policy Status (Politika Durumu): Sadece okunur; Aktif veya Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Toggle ile değiştirilebilir. Name (Ad) — Zorunlu: Örnek: Production_JOSE. 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: “Çıkış gövdesini imzalı JWT’ye dönüştürür”. Maks. 1000 karakter; politikanın amacını açıklar. |
| Adım 3: Politika Yapılandırması (Policy Configuration) | JOSE Target (İmzalanacak/Şifrelenecek Hedef) — Zorunlu: Üretilen JWT/JWE’nin nereye yazılacağını belirler. Gövde = istek/yanıt gövdesine, Authorization Başlığı = Authorization header’ına, Değişkenden Seç = bir proje değişkenine, Boş = token üretilir ama hedefe yazılmaz (sadece zincir politikalarında ara veri için kullanılabilir). Tüketicinin token’ı nereden beklediğine göre seçin; örn. REST yanıtında gövde bekleniyorsa Gövde, mobil istemci header bekliyorsa Authorization Başlığı seçilir. Politika çalıştığında token seçilen hedefe yazılır; Boş ise sadece imza/şifreleme işlemi yapılır, çıktı hedefe yazılmaz.JOSE Target Variable (Hedef Değişken) — Koşullu (sadece Hedef = Değişkenden Seç iken): Üretilen token’ın yazılacağı proje değişkenini işaret eder; politika çalışırken token bu değişkene yazılır. Değişken Seç ile proje değişkeni atayın; Güncelle ile değişken tanımını düzenleyebilirsiniz. Sonraki politikalar veya akış bu değişkenden token’ı okuyabilir; veri manipülasyonu zincirinde sık kullanılır. JWT Claims Claim (Ham Veri için Claim Adı) — Koşullu (JOSE Target ≠ Boş iken): Mevcut istek/yanıt gövdesi (ham veri) JWT payload içinde hangi claim adıyla yer alacak onu belirler; varsayılan data. Ham veri belirtilen claim adıyla payload’a yazılır. Ham verinin JWT payload’da hangi claim adıyla yazılacağını belirler; varsayılan data. Tek bir claim’de tüm gövdeyi taşımak için örn. data veya payload yazın; boş bırakırsanız ham veri doğrudan payload yapısına yansır. Tüketici token’ı decode ettiğinde bu isimle claim’i görür.Escape JSON String (JSON String’i, String Olarak Kullan): Koşullu (JOSE Target ≠ Boş iken): Ham veri JSON string olduğunda bunun JWT’de string claim olarak mı yoksa nesne olarak mı yazılacağını seçer. Açıksa JSON escape edilip tek string claim olarak yazılır; kapalıysa parse edilip nesne/array olarak yazılabilir.string’in |
| Adım 4: Claim Ayarları (Claim Ayarları paneli) | Add Issue Time (Issue Time Ekle): Token’a iat (issued at) claim’i eklenir. Tüketici token yaşını ve geçerliliğini kontrol edebilir.Add JWT ID (Üretilmiş ID Ekle): Benzersiz jti (JWT ID) claim’i eklenir. Tekrar kullanım veya revocation listelerinde token tanımlanabilir.Add Type to Header (Tip Bilgisi Ekle): JWT header’a tip bilgisi eklenir. Tüketici token türünü header’dan okuyabilir. Type Value — Koşullu, zorunlu (sadece Add Type to Header açıkken): Header’a yazılacak tip değeri (örn. JWT). Örn. JWT veya JWE girin.Add Issuer (Issuer Ekle): Token’a iss (issuer) claim’i eklenir. Doğrulama tarafında issuer veya anahtar eşleştirme için kullanılır.Issuer — Koşullu, zorunlu (sadece Add Issuer açıkken): Issuer değerini girer; genelde URL veya servis adı. Örn. https://api.sizin-alan.com girin.Add Audience (Audience Ekle): Token’a aud (audience) claim’i eklenir. Tüketici kendi tanımlayıcısının listede olup olmadığını kontrol eder.Audience List — Koşullu, zorunlu (sadece Add Audience açıkken): aud claim’ine yazılacak değerlerin listesi. Metin kutusuna değer yazıp onaylayarak chip olarak ekleyin; en az bir değer gerekir.Add Subject (Subject Ekle): Token’a sub (subject) claim’i eklenir. Yetkilendirme ve kimlik eşlemesinde kullanılır.Subject — Koşullu, zorunlu (sadece Add Subject açıkken): Subject değerini girer (kullanıcı ID’si, servis adı vb.). Add Expiration Time (Expiration Time Ekle): Token’a exp (expiration) claim’i eklenir. Süre dolunca token geçersiz sayılır.Expiration Time Value + Expiration Time Unit — Koşullu, zorunlu (sadece Add Expiration Time açıkken): Geçerlilik süresini sayı + birim (saniye, dakika, saat) olarak tanımlar. Örn. 60 + MINUTE. Additional Claim Map (Ek Claim Listesi): İstediğiniz ek claim’leri anahtar–tip–değer olarak eklemenizi sağlar. + ile satır ekleyin; Key = claim adı, Value Type = STRING/NUMBER/BOOLEAN vb., Value = değer. Token payload’ında bu claim’ler yer alır. |
| Adım 5: İmza Konfigürasyonu — JWS Uygulama Ayarları (Signature paneli) | Sign (İmzala): Toggle; token imzası açılır/kapanır. Sign by Issuer (İstemci JWK’sı ile İmzala): Toggle; issuer tarafından imza kullanılır. Aşağıdaki alanlar sadece Sign açık ve Sign 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: • Dijital İmzalama için JWK (jwkIdForValidationAndSign) — Zorunlu: Açılır liste (Secret Manager’daki imza JWK’ları), Temizle ve Yeni butonları. Seçilen JWK tabloda (Ad, Açıklama, Tip, Algoritma) gösterilir; satıra tıklayarak düzenleme/detay açılır. — Dinamik HTTP seçiliyse: Anahtar, politika yapılandırmasında tanımlı HTTP isteği ile uzaktan alınır. Dinamik HTTP nasıl çalışır: (1) İstek gönderimi: Test Console’da girilen URL, method, header ve gerekirse body ile HTTP isteği atılır (kaydetmeden önce URL zorunludur). (2) Yanıt işleme: Gelen yanıt gövdesi, Key Extraction Variable ile tanımlı ifadeye (örn. JSONPath) göre işlenir; tek bir anahtar/sertifika/JWK parçası çıkarılır. (3) Anahtar kullanımı: Çıkarılan ham veri Key Format ve Key Algorithm ayarlarına göre parse edilir ve imzalama için kullanılır. (4) Önbellek (isteğe bağlı): Enable Cache açıksa Apply By ile seçilen değişkenin değeri (örn. issuer) cache key olarak kullanılır; aynı değer için anahtar tekrar istenmez, TTL ve Capacity sınırlarına tabidir. JWKS veya benzeri endpoint’lerden çalışma anında güncel anahtarlar alınabilir. • HTTP İstek Yapılandırması (httpRequest): Test Console bileşeni; servis URL ve istek (method, header, body vb.) tanımlanır. Zorunlu; kaydetmeden önce URL dolu olmalı. • Key Extraction Variable (Anahtar Çıkarma Değişkeni) — Zorunlu: 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 imza anahtarı olarak kullanılır.• Key Format (Anahtar Formatı) — Zorunlu: Yanıt formatı: Otomatik Algıla, Genel Anahtar, Özel Anahtar, Sertifika, JWK JSON. NONE + Yanıtı Ayrıştır (Try It) ile otomatik algılanabilir. • Key Algorithm (Anahtar Algoritması) — Zorunlu: Algoritma listesi (örn. NONE, RS256, ES256). Yanıtı Ayrıştır ile otomatik atanabilir. • Kid (Anahtar ID) — İsteğe bağlı: JWKS veya yanıtta birden fazla anahtar varsa hangisinin kullanılacağını belirtir. Aynı endpoint çoklu anahtar döndürüyorsa (örn. rotasyon) doğru anahtar seçilir. • Enable Cache (Önbelleği Etkinleştir): Toggle; açıldığında aşağıdaki cache alanları görünür ve cache açıkken zorunludur: - Apply By (Uygula Kriteri): Cache’in hangi değişkene göre uygulanacağı; değişken seçici — zorunlu. - Capacity (Kapasite): Sayı, min 1 — zorunlu. - TTL: Sayı, min 1 (saniye) — zorunlu. - Cache Storage Type (Önbellek Depolama Tipi): LOCAL veya DISTRIBUTED — zorunlu. - Respect Cache Invalidation Headers (Cache Geçersiz Kılma Başlıklarına Uy): Checkbox. - Cache Connection Timeout (Cache Bağlantı Zaman Aşımı, saniye): Sayı, min 1 — zorunlu. - Cache Error Handling Type (Cache Bağlantı Hatası İçin Aksiyon): CONTINUE vb. — zorunlu. • Retry on Key Error (Anahtar Getirme Hatasında Tekrar Dene): Toggle. • Invalidate Cache on Validation Error (Doğrulama Hatasında Cache’i Temizle ve Anahtarı Yeniden Getir): Toggle; sadece cache açıkken görünür. • Yanıtı Ayrıştır (Parse Response / Try It): Dinamik HTTP anahtar yapılandırmasını kaydetmeden test etmenizi sağlar. (1) HTTP İstek Yapılandırması (URL, method, header/body), Key Extraction Variable, Key Format, Key Algorithm (ve isteğe bağlı Kid) alanlarını doldurun. (2) Yanıtı Ayrıştır butonuna tıklayın; sistem isteği gönderir, yanıtı alır ve Key Extraction Variable ile anahtarı çıkarıp seçili formata göre parse eder. (3) Sonuç diyaloğu açılır: başarılı ise Detected Key Format ve Detected Algorithm (Key Format = Otomatik Algıla veya Key Algorithm = NONE ise) otomatik politika alanlarına yazılabilir; hata varsa Error Details ve HTTP durum kodu gösterilir. Test sonuçlarını yorumlama: Başarı (Success) = HTTP isteği başarılı, anahtar çıkarıldı ve parse edildi; Detected Key Format / Detected Algorithm görünüyorsa kaydedebilirsiniz. Hata (Error) = İstek başarısız, zaman aşımı veya anahtar çıkarılamadı; Error Details ve HTTP Response Status’a bakın (URL/erişim, Key Extraction Variable path, Key Format/Algorithm uyumu). Extracted Key String / Key Info = Çıkarılan ham anahtar ve tip; doğrulama için kullanın; hassas veri üretimde loglara düşmemesine dikkat edin. |
| Adım 6: Şifreleme Konfigürasyonu — JWE Uygulama Ayarları (Encrypt paneli) | Encrypt (Şifrele): Toggle. Encryption Method (Şifrele Metodu) — Koşullu, zorunlu: Sadece Encrypt açıkken görünür; şifreleme metodu listesinden seçin. Encrypt by Issuer (İstemci JWK’sı ile Şifrele): Toggle; issuer tarafında şifreleme kullanılır. Aşağıdaki alanlar sadece Encrypt açık ve Encrypt 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: • Şifreleme 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: Adım 5 ile aynı mantık: HTTP İstek Yapılandırması (URL zorunlu), Key Extraction Variable, Key Format, Key Algorithm, Kid, Enable Cache ve Apply By. Dinamik HTTP’nin nasıl çalıştığı (istek gönderimi, yanıt işleme, anahtar kullanımı, önbellek) ve Yanıtı Ayrıştır (Try It) butonunun kullanımı ile test sonuçlarının yorumlanması Adım 5’te anlatıldığı gibidir; şifreleme panelinde de aynı alanlar ve aynı akış geçerlidir. |
| Adım 7: Data Manipülasyonu (Data Manipülasyonu paneli) | Encoded Claims Target for Data Manipulation (Oluşturulan JWT/JWE için Injection Target) — Zorunlu: Token’ın yazılacağı hedef: Gövde, Authorization Başlığı veya Değişkenden Seç. Decoded Claims Target Variable (Target for Decoded Claims için Hedef Değişken) — Koşullu, zorunlu: Sadece Injection Target = Değişkenden Seç iken görünür. Decode edilmiş claim’lerin yazılacağı proje değişkeni; Değişken Seç / Farklı Seç / Kaldır ve Güncelle butonları ile atanır. |
| Adım 8: Koşul Tanımlama (Condition sekmesi) — İsteğe bağlı | Condition sekmesine geçin. Query Builder ile koşul kuralları tanımlayın; politikanın hangi durumda aktif olacağı belirlenir. Ö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 9: 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 10: Kaydetme | Sağ üstteki [Save] butonuna tıklayın. Kontrol listesi: Benzersiz isim; JOSE Target ve (Değişkenden Seç ise) JOSE Target Variable; Add Type to Header ise Type Value; Add Issuer ise Issuer; Add Audience ise en az bir Audience; Add Subject ise Subject; Add Expiration Time ise Expiration Time Value + Unit; Sign açıksa ve Sign by Issuer kapalıysa Key Source Mode’a göre Gömülü’da JWK seçili, Dinamik HTTP’da URL + Key Extraction Variable + Key Format (+ cache açıksa Apply By, Capacity, TTL vb.); Encrypt açıksa Encryption Method ve (Encrypt by Issuer kapalıysa) aynı JWK/Dinamik HTTP kuralları; Encoded Claims Target; Değişkenden Seç ise Decoded Claims Target Variable. 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. |
| Gömülü JWK ile İmza/Şifreleme | - İmza veya şifreleme panelinde Key Source Mode = Gömülü iken 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. |
| Dynamic HTTP ile Anahtar Çekme | - Key Source Mode = Dinamik HTTP seçin. - HTTP Request alanında Test Console ile servis URL ve isteği tanımlayın. - Key Extraction Variable (zorunlu), Key Format, Key Algorithm belirleyin; cache açacaksanız Apply By değişkeni, Capacity, TTL ve diğer cache alanlarını doldurun. - Parse Response (Try It) ile yanıtı test edin; başarılıysa algılanan format/algoritma otomatik atanabilir. |
| Token Zinciri Manipülasyonu | - Oluşturulan JWT/JWE için Injection Target alanından token’ın yazılacağı hedefi (Gövde, Authorization Başlığı veya Değişkenden Seç) seçin. - Değişkenden Seç ise decode edilmiş veriyi başka politikaya aktaracak Target for Decoded Claims için Hedef Değişken 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 ve Dinamik Anahtar Yönetimi | Kötü: Süresi dolmuş anahtarları veya hatalı Dynamic HTTP URL’ini kullanmaya devam etmek. İyi: Embedded JWK rotasyonunu manuel aralıklarla yapmak; Dynamic HTTP’de Try It ile test edip cache kullanmak. En İyi: Secret Manager üzerinden otomatik rotasyon (Embedded) veya cache + retry/invalidate ayarları (Dynamic HTTP) ile güvenilir anahtar tedariki. |
| İ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 | Embedded modda JWK’ları sadece Secret Manager içerisinde tutun; Dynamic HTTP’de kullanılan endpoint’in güvenliği ve cache’in erişim kısıtları önemlidir. |
| 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 veya Dynamic Key Eşlemesi | Neden kaçınılmalı: Eksik veya farklı algoritmaya sahip JWK/format seçimi token doğrulamasını bozar. Alternatif: İlgili algoritma için filtrelenmiş JWK listesini (Embedded) veya doğru Key Format/Algorithm ve Try It (Dynamic HTTP) 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. |
| Embedded 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. |
| Dynamic HTTP Cache | Öneri: Enable Cache açık, Capacity ve TTL uygun değerlerde olsun; böylece uzak anahtar tekrarlı çekilmez. Etki: Gecikme ve dış servis yükü 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? | Key Source Mode = Gömülü iken Secret Manager JWK listesi açılır; uygun algoritma ve amaçla eşleşen anahtar seçilir veya yeni anahtar oluşturulur. |
| Teknik | Dynamic HTTP ile anahtar nasıl kullanılır? | Key Source Mode = Dinamik HTTP seçilir; HTTP Request (Test Console) ile URL ve istek, Key Extraction Variable (zorunlu), Key Format ve Key Algorithm tanımlanır. İsteğe bağlı cache ve Try It (Parse Response) ile test edilir. |
| Teknik | Değişkenden hedef seçince ne olur? | JOSE Target = Değişkenden Seç ise 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 | Type Value ne zaman zorunlu? | Add Type to Header açıkken header’a eklenecek tip değeri (örn. JWT) zorunludur. |
| 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. |