Genel Bakış
Amacı Nedir?
API Proxy (API Vekil Sunucusu)üzerinden geçen isteğin içeriğinin değiştirilmediğini garanti altına almak için dijital imzayı doğrular.- İsteğin gerçekten yetkili istemciden geldiğini kanıtlamak için imza üretiminde kullanılan anahtar veya sertifikayı kontrol eder.
- Çoklu imza tanımı sayesinde farklı endpoint veya payload türleri için ayrı doğrulama kuralları uygulamaya imkan tanır.
- İmza doğrulama algoritmasını dinamik olarak belirleyerek farklı imza formatlarıyla uyumluluk sağlar.
Ç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ü: Dijital İmza 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ı?
- Dijital İmza Doğrulama Kontrolü: Tanımlı her doğrulama girdisi için istekteki imza değişkeni alınır, seçilen algoritma (belirtilmiş veya değişkenden okunan) ile kaynak veri çözümlenir ve seçilen anahtar/sertifika ile imza doğrulanır. Girdi BASE64 veya HEX kodlamasına göre çözülür.
- Karar Verme:
- Eşleşme Var: Tüm tanımlar için imza doğrulanır, istek işleme akışına devam eder.
- Eşleşme Yok: Herhangi bir tanım başarısız olursa istek durdurulur, yapılandırılan hata mesajı döndü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
- Çoklu İmza Tanımı Yönetimi: Farklı payload veya endpoint kombinasyonları için birden fazla dijital imza doğrulama girdisi tanımlanabilir; her girdi bağımsız parametrelerle çalışır.
- Dinamik Algoritma Seçimi: İmza algoritması sabit değer olarak belirlenebilir veya istekteki değişkenlerden otomatik alınarak farklı imzalama stratejilerine uyum sağlanır.
- Gizli Anahtar ve Sertifika Entegrasyonu: Secret Manager’dan Crypto Key veya sertifika seçilerek merkezi anahtar yönetimiyle uyumlu güvenlik sağlar.
- 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
- Değişken Bazlı İmza Çözümleme: İmza ve kaynak veri, global değişken deposundan seçilerek runtime sırasında parametrik doğrulama yapılmasını sağlar.
- Algoritma Keşfi: FIND modu, imza algoritmasını istek içeriğinden okuyarak aynı politika ile çok sayıda istemciyi destekler.
- Revoked Sertifika Uyarısı: Liste ekranında iptal edilmiş sertifikalar kırmızı renkle belirtilir, geçersiz sertifikaların tekrar kullanılmasını engeller.
- 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ç |
|---|---|---|---|
| REST JSON İsteği İmza Doğrulama | Mobil uygulama istekleri JSON gövdesi ve Base64 imza taşıyor | sourceVar=body.json, signatureVar=header.X-Signature, inputEncodingType=BASE64, signatureAlgorithm=SHA256withRSA, Crypto Key seçili | İstek yalnızca imza eşleşirse devam eder, aksi halde 403 döner |
| XML Doküman İmzalama Kontrolü | BPM sistemi SOAP/XML ile imzalı içerik gönderiyor | sourceVar=body.xml, signatureVar=body.signature, inputEncodingType=HEXADECIMAL, signatureAlgorithm=SHA1withDSA, Sertifika seçili | XML dokümanı değiştirilirse politika isteği reddeder |
| Algoritmayı Header’dan Alma | Birden fazla algoritma kullanan müşteriler aynı endpoint’i çağırıyor | sourceOfAlgorithm=FIND, signatureAlgorithmVar=header.X-Signature-Alg, signatureVar=header.X-Signature, sourceVar=body.raw | Header’da bildirilen algoritma ile imza doğrulanır, eksik/yanlışsa hata üretilir |
| Revoked Sertifika Denetimi | İptal edilmiş sertifika ile imzalanan isteği engelleme | Sertifika listesinde revoked olarak işaretli kaydı seçmeden önce uyarı notu eklenir, güncel sertifika zorunlu kılınır | İptal edilmiş sertifika ile gelen istekler 403 Forbidden döner |
| Çoklu Bölüm İmzalama | Aynı istekte hem payload hem metadata imzalanıyor | İki ayrı doğrulama tanımı oluşturulur; her biri farklı sourceVar ve signatureVar kullanır | Her iki imza da doğrulanırsa istek geçer, biri hatalıysa engellenir |
| Harici Anahtar Rotasyonu | Anahtar rotasyon sürecinde eski ve yeni anahtarlar aynı anda kullanılacak | İki tanım eklenir; biri eski Crypto Key, diğeri yeni Crypto Key ile | Geçiş sürecinde her iki anahtar da kabul edilir, rotasyon sonrası eski tanım silinir |
| Performans İzleme (opsiyonel) | Yoğun trafik altında doğrulama süresi ölçülmek isteniyor | Condition ile belirli Header değerlerine sahip isteklerde politika aktif, Logging ile süre tutulur | Kritik işlemlerde doğrulama sürer, gereksiz isteklere uygulanmaz |
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 Dijital İmza 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 → Dijital İmza 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_DigitalSignVerify- 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: “Mobil imzalı JSON isteği doğrulaması” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Dijital İmza Tanımlarını Oluşturma | [+ Add Verification] ile modal açın. - Signature Var: İmzanın bulunduğu değişkeni seçin. - Source Var: İmzanın üretildiği ham veriyi temsil eden değişkeni seçin. - Input Encoding Type: İmzanın BASE64 veya HEX olduğunu belirtin. - Açıklama girerek tanımı gruplayın. |
| Adım 4: Algoritma ve Anahtar Yapılandırması | Modal içinde Source of Algorithm alanını belirleyin. - SPECIFY seçilirse algoritmayı listeden seçin. - FIND seçilirse Signature Algorithm Var ile algoritmayı istekteki değişkenden okuyun. - Key or Certificate bölümünde Crypto Key veya Sertifika modunu seçin; gerekirse yeni anahtar/sertifika oluşturma diyaloglarını kullanın. |
| Adım 5: Çoklu Tanım ve Öncelik Yönetimi | - Birden fazla imza tanımı ekleyin. - Tanımlar listedeki sırayla değerlendirilir. - Her tanım için düzenleme/silme işlemleri aynı modal üzerinden yapılır. - Öneri: Farklı endpoint’ler için anlamlı açıklamalar kullanı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 imza tanımı 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 |
|---|---|
| Runtime Algoritma Seçimi | - Source of Algorithm alanını FIND olarak ayarlayın.- Algoritma değerini taşıyan değişkeni Signature Algorithm Var olarak seçin.- Değişkenin istekte zorunlu olarak gönderildiğinden emin olun ve eksik durumda hata mesajı tanımlayın. |
| Anahtar/Sertifika Rotasyonu | - Yeni ve eski anahtarlar için iki ayrı imza tanımı oluşturun. - Condition sekmesinde tarih veya header bazlı kural tanımlayarak geçiş sürecini yönetin. - Rotasyon tamamlandığında eski tanımı silerek politika listesini sadeleştirin. |
| Çoklu Payload Doğrulama | - Her payload bölümü için ayrı sourceVar ve signatureVar seçin.- Tanımları anlamlı açıklamalarla belgeleyin. - Tanımların sırasını kontrol ederek kritik kontrolleri üstte konumlandırın. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| İsimlendirme Stratejisi | Kötü: policy1İyi: DigitalSignVerify_ProdEn İyi: DSV-Prod-CustomerPayload |
| Değişken Kullanımı | Kötü: Hard-coded header isimleri İyi: Önceden tanımlı değişkenleri kullanmak En İyi: Dinamik değişkenleri Query Builder koşullarıyla doğrulamak |
| Algoritma Yönetimi | Kötü: Tüm istemcilerde aynı algoritmayı varsaymak İyi: Ana kullanılan algoritmayı SPECIFY ile tanımlamak En İyi: FIND modu ile istemci bazlı algoritmaları desteklemek |
| Anahtar/Sertifika Güncelleme | Kötü: Sertifikayı manuel değiştirmek İyi: Yeni sertifikayı tanımlayıp eskisini silmek En İyi: Rotasyon sürecinde iki tanımı paralel çalıştırıp geçişten sonra temizlik yapmak |
| Hata Mesajı Yönetimi | Kötü: Varsayılan mesajı olduğu gibi bırakmak İyi: Hata kodunu belirtmek En İyi: İzlenebilirlik için errorCode ve hedef log referansını eklemek |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Anahtar Gizliliği | Crypto Key referanslarını sadece yetkili projelerle paylaşın; gereksiz erişimleri engelleyin. |
| Sertifika Geçerliliği | Revoked sertifikaları tekrar kullanmayın; liste ekranındaki kırmızı uyarılara dikkat edin. |
| Hata Mesajı İçeriği | Saldırganlara bilgi vermemek için hata mesajında algoritma veya anahtar detaylarını paylaşmayın. |
| Kayıt ve İzleme | Başarısız doğrulama denemelerini SIEM sistemine yönlendirerek olası saldırıları erken tespit edin. |
| Koşullu Aktifleştirme | Kritik endpoint’ler için ek Condition kriterleri tanımlayarak gereksiz doğrulama yükünü azaltın, istek yüzeyini sınırlayın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Eksik İmza Tanımı | Neden kaçınılmalı: Tanım olmadan politika devreye girmez. Alternatif: En az bir tanımı zorunlu alanları doldurarak ekleyin. |
| Yanlış Encoding Seçimi | Neden kaçınılmalı: Base64/HEX uyumsuzluğu doğrulamayı bozar. Alternatif: İmza sağlayıcısından alınan bilgiye göre encoding seçin. |
| Revoked Sertifika Kullanımı | Neden kaçınılmalı: Güvenlik riski oluşturur ve doğrulama başarısız olur. Alternatif: Geçerli sertifikayı Secret Manager’dan seçin. |
| Koşulsuz Global Etki | Neden kaçınılmalı: Tüm trafiği gereksiz doğrulamaya zorlayarak performansı düşürür. Alternatif: Condition ile sadece kritik endpoint veya istemcileri hedefleyin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Tanım Sayısı | Öneri: Benzer imza gereksinimlerini tek tanımda birleştirin. Etki: Her istekte yapılan doğrulama sayısı azalır. |
| Algoritma Kaynağı | Öneri: Sabit algoritma kullanabiliyorsanız SPECIFY seçin. Etki: FIND modundaki ek değişken çözümlemesini ortadan kaldırır. |
| Condition Kullanımı | Öneri: Sadece imzalanmış isteklerin geleceği endpoint’leri koşul ile hedefleyin. Etki: Gereksiz doğrulama maliyetini düşürür. |
| Anahtar Yönetimi | Öneri: Aynı anahtarı birden fazla tanımda tekrar etmeyin, ortak senaryoları gruplayın. Etki: Bellek kullanımını ve lookup süresini azaltır. |
| İzleme | Öneri: Başarısız doğrulama sayısını metrik olarak toplayın. Etki: Performans anomalilerini ve saldırı girişimlerini erken tespit edersiniz. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Farklı endpoint’lerde farklı imza kuralları uygulayabilir miyim? | Evet, her endpoint için ayrı Condition tanımlayıp uygun imza tanımlarını ekleyebilirsiniz. |
| Genel | Politika pasif olduğunda kayıtlı tanımlar silinir mi? | Hayır, pasif moda alınca yapılandırma korunur ve yeniden etkinleştirildiğinde aynı ayarlarla çalışır. |
| Teknik | İmza algoritmasını runtime’da belirleyemezsem ne olur? | FIND seçili ancak değişken boşsa doğrulama başarısız olur ve özelleştirilmiş hata mesajı döner; SPECIFY moduna geçebilirsiniz. |
| Teknik | Sertifika yenilendiğinde politikayı nasıl güncellerim? | Yeni sertifikayı Secret Manager’a ekleyip tanımda sertifika referansını güncelleyin veya paralel tanım ekleyerek kesintisiz geçiş yapın. |
| Kullanım | Aynı politika hem global hem local kullanılabilir mi? | Global politikayı localize ederek kopyalayabilirsiniz; local kopya sadece seçili API’de görünür. |
| Kullanım | İmza başarılı olsa bile özel HTTP kodu döndürebilir miyim? | Evet, Error Message Customization sekmesinde varsayılan yanıtı değiştirerek farklı statusCode veya payload tanımlayabilirsiniz. |