mTLS Kimlik Doğrulama

İstemci TLS sertifikalarını doğrulayarak güvenli karşılıklı kimlik doğrulama sağlayabilirsiniz

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

​

Genel Bakış

​

Amacı Nedir?

• Kurumsal API Proxy (API Vekil Sunucusu) trafiğinde istemci sertifikasını zorunlu kılarak kimlik doğrulama yapmak ve sadece yetkili istemcilerin erişimini sağlamak.
• Sertifika hiyerarşisinin güvenilir Certificate Authority (CA) zincirleri ile uyuştuğunu doğrulayarak sahte sertifika riskini ortadan kaldırmak.
• İstemci sertifikasını önceden tanımlı Issuer ACL listeleriyle eşleştirip, belirli kurum veya cihazlara özel erişim stratejisi oluşturmak.
• Yetkilendirme modülüyle birlikte çalışarak sertifikadan elde edilen kimliği politikaya bağlı rol kontrolleriyle pekiştirmek.

​

Çalışma Prensibi

1. İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. Politika Kontrolü: mTLS 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ı?
3. Sertifika ve Issuer Doğrulaması: mTLS handshake tamamlandıktan sonra istemci sertifikasının geçerlilik tarihleri, imzası ve tanımlı issuer listesi doğrulanır; isteğe bağlı olarak Issuer ACL kayıtlarıyla eşleşme aranır.
4. Karar Verme:
   • Eşleşme Var: Sertifika kabul edilir, gerekirse kimlik bilgisi ve roller header alanlarına eklenir, isteğin yönlendirilmesine izin verilir.
   • Eşleşme Yok: Sertifika veya issuer doğrulaması başarısız olur, isteğin yönlendirilmesi durdurulur ve yapılandırılmış hata yanıtı döndürülür.
5. 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

• Sertifika Issuer Doğrulama: Gelen istemci sertifikasının issuer bilgilerini kayıtlı CA zinciri ve Issuer ACL listeleriyle karşılaştırır.
• Dinamik Sertifika Geçerlilik Kontrolü: Sertifikanın tarih ve imza bütünlüğünü her istek için kontrol ederek geçersiz sertifikaları anında reddeder.
• ACL Tabanlı Erişim: Issuer bazlı erişim kontrollerini IP denetimi ile genişleterek belirli ağ segmentlerine özgü izinler tanımlar.
• 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

• Header Enjeksiyonu Yönetimi: Sertifika öznesinden çıkarılan kullanıcı kimliğini ve rolleri özel header alanlarına yazarak downstream servislerine aktarır.
• Yetkilendirme Servisi Entegrasyonu: API, veritabanı veya Secret Manager kaynaklı yetkilendirme akışlarını devreye alarak mTLS kimlik doğrulamayı rol tabanlı erişimle birleştirir.
• Metot Bazlı Yetki Kısıtları: HTTP metoduna göre erişim kuralları tanımlayarak hassas operasyonları granular düzeyde kontrol eder.
• 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ç
Finans Kurumsal Erişim	Finansal servisler sadece şirket laptoplarından çağrılıyor	Issuer ACL’e kurum CA sertifikası eklenir, validateCertificatesIssuer ve validateACLForIssuer aktif edilir	Kurumsal cihazlardan gelen istekler kabul edilir, diğerleri 403 döner
IoT Cihaz Kimliği	Edge gateway’ler sertifika ile bağlanıyor	validateCertificate açık, ACL’de cihaz sertifikaları listelenir	İzinli cihaz sertifikaları yönlendirilir, süresi geçmiş sertifikalar 401 alır
Partner API Erişimi	Dış partnerlere sınırlı endpoint erişimi	Query Builder’da path koşulu, ACL’de partner issuer sertifikası	Partner sertifikası eşleşirse sadece tanımlı endpoint erişimi sağlanır
Çoklu Ortam Yönetimi	Test ortamı için gevşek kontrol, canlıda sıkı kontrol	Geliştirme ortamında validateACLForIssuer pasif, canlıda aktif	Geliştirme ortamı esnek kalır, Canlı Ortam’da sadece tanımlı sertifikalar kabul edilir
Rol Bazlı Yetki	Aynı sertifikayla farklı servis rolleri uygulanacak	enableAuthorization aktif, roller header’a yazılır	Downstream servis rol header’ını okuyarak yetki verir
IP Kısıtlaması	Sertifika paylaşımı riskine karşı IP eşlemesi	checkClientIpAddress etkin, ACL’de IP eşleşmesi aranır	Sertifika-IP eşleşmeyen istekler reddedilir
İsteğe Bağlı Senaryo	(opsiyonel)

​

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 mTLS 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 → mTLS 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_mTLSAuth - 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: “Kurumsal istemciler için mTLS kimlik doğrulaması” - Maks. 1000 karakter. - Politikanın amacını açıklayın.
Adım 3: Variable Kullanımı	- Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz. - Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. - Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar. - Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Adım 4: Sertifika Doğrulama Parametreleri	- Validate Certificates Issuer: CA zincirinin tanımlı issuer kayıtlarıyla eşleşmesini zorunlu kılar. - Validate Certificate: Sertifikanın geçerlilik tarihlerini ve imzasını kontrol eder. - Validate ACL For Issuer: Issuer bazlı ACL tablosunu devreye alır; Issuer listesi olmadığı durumda Uyarı: Politika 401 döndürebilir.
Adım 5: ACL ve IP Eşlemesi	- Check Client IP Address: Sertifika ile kayıtlı istemci IP’sinin eşleşmesini arar. - Issuer ACL yönetim ekranından yetkili IP bloklarını tanımlayın. - Sertifika paylaşımı riskine karşı IP kontrolünü etkin tutun.
Adım 6: Header ve Yetkilendirme Ayarları	- Add User To Header: Sertifika öznesinden çıkarılan kullanıcı kimliğini User Header Name alanına yazar. - User Header Name: Varsayılan X-Authenticated-UserId, ihtiyaç halinde özelleştirin. - Enable Authorization: Roller ve metot bazlı kontrolleri aktif eder; Authorization sekmesindeki kaynak ve roller tanımlanmalıdır.
Adım 7: 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ımlamazsanız politika her zaman aktiftir
Adım 8: 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 9: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir issuer veya ACL girdisi mevcut. Sonuç: - Politika listeye eklenir. - API’lere bağlanabilir. - Global politikaysa otomatik uygulanır.

Koşullar ve Hata Mesajı Özelleştirme panellerinin açıklaması için Politika Nedir? sayfasındaki Koşullar ve Hata Mesajı Özelleştirme (Error Message Customization) bölümlerini inceleyebilirsiniz.

Hata mesajı yapılandırmasının tüm katmanları, öncelik sırası ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

​

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
Issuer ACL Yönetimi	- Issuer başına birden fazla Subject Alternative Name kaydı yapılabilir. - ACL kayıtlarını ortam bazlı filtreleyin. - Öneri: ACL değişikliklerinden sonra test API çağrısı yapın.
Secret Manager ile Yetkilendirme	- useSecretManagerForAuthorization seçildiğinde kimlik bilgileri güvenle saklanır. - Secret güncellemelerinde politikayı yeniden deploy edin. - Rotasyon sonrası eski secret’ları silin.
Metot Bazlı Yetki Politikaları	- HTTP metoduna göre allow/deny kuralları tanımlayın. - policyAuthorizationMethodDefList içerisinde endpoint + metod eşlemesi girin. - Tüm değişikliklerden sonra Postman koleksiyonu ile doğrulama önerilir.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Sertifika Yönetimi	Kötü: CA listelerini manuel güncellemeyi unutmak İyi: CA yenilendiğinde Issuer ACL’i güncellemek En İyi: Otomatik CA senkronizasyon pipeline’ı kurmak
Yetkilendirme Entegrasyonu	Kötü: enableAuthorization açıkken rol listelerini boş bırakmak İyi: Roller için minimum yetki prensibini uygulamak En İyi: Roller değiştirildiğinde CI/CD içinde otomatik test çalıştırmak
Header Kullanımı	Kötü: Downstream servislerin X-Authenticated-UserId header’ını doğrulamaması İyi: Header doğrulamasını gateway arkasındaki servislerde uygulamak En İyi: Header imza mekanizması eklemek
Koşul Yönetimi	Kötü: Tüm endpoint’lere politikayı koşulsuz uygulamak İyi: Hassas endpoint’leri Query Builder ile hedeflemek En İyi: Koşulları ortam ve versiyon bazlı yapılandırmak
Deployment Süreci	Kötü: Canlı ortamda doğrudan değişiklik yapmak İyi: Test ortamında sertifika senaryolarını denemek En İyi: Blue/Green deployment planı oluşturmak.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Sertifika İptal Listesi	CRL/OCSP kontrolleri gateway dışında yapılıyorsa periyodik olarak güncelleyin.
Issuer ACL Sertliği	Issuer ACL’i boş bırakmak istemci doğrulamasını zayıflatır. Mutlaka yetkili issuer ekleyin.
Header Koruması	Downstream servislerde header spoofing’e karşı imza veya mTLS termination sonrası güvenli iletişim kullanın.
IP Eşleşmesi	checkClientIpAddress devredeyse dinamik IP kullanan istemciler için whitelist’i güncel tutun.
Loglama	Sertifika doğrulama hatalarını güvenli loglarda maskeli olarak saklayın, kişisel verileri anonimleştirin.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Issuer ACL Eksikliği	Neden kaçınılmalı: Tüm sertifikalar kabul edilebilir hale gelir. Alternatif: Issuer ACL’e minimum güvenilir CA setini ekleyin.
İzin Verilmeyen Header Kullanımı	Neden kaçınılmalı: Downstream servislerde kimlik taklidi oluşur. Alternatif: Header isimlerini kurum standartlarına göre sabitleyin.
Test Ortamını Atlamak	Neden kaçınılmalı: Sertifika zincirindeki hatalar canlıda kesinti yaratır. Alternatif: Her değişikliği otomatik test ile doğrulayın.
IP Kontrolünü Gereksiz Kapamak	Neden kaçınılmalı: Sertifika paylaşımına açık kapı bırakır. Alternatif: Dinamik IP yönetimi için ayrı ACL grupları oluşturun.

​

Performans İpuçları

Kriter	Öneri / Etki
Handshake Optimizasyonu	Öneri: TLS oturum yeniden kullanımı (session resumption) etkinleştirin. Etki: Handshake süresi azalır, gecikme düşer.
Sertifika Önbelleği	Öneri: Doğrulanmış sertifikaları kısa süreli bellekte tutun. Etki: Tekrarlayan çağrılarda CPU yükü azalır.
Issuer ACL Lookup	Öneri: ACL sorgularını bellek içi veri yapılarıyla yönetin. Etki: Büyük ACL listelerinde sorgu hızı artar.
Loglama Seviyesi	Öneri: Debug loglarını sadece Geliştirme ortamında aktif edin. Etki: Canlı Ortam’da I/O yükü ve disk kullanımı azalır.
Authorization Çağrıları	Öneri: Yetkilendirme servis çağrılarına timeout ve Circuit Breaker ekleyin. Etki: Harici servis yavaşlamaları API yanıt süresini etkilemez.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	mTLS kimlik doğrulama nedir?	Mutual TLS (mTLS), hem istemci hem de sunucunun birbirlerinin sertifikalarını doğruladığı çift yönlü kimlik doğrulama mekanizmasıdır.
Genel	Issuer ACL nedir?	Issuer ACL, hangi Certificate Authority (CA) sertifikalarının kabul edileceğini tanımlayan erişim kontrol listesidir.
Teknik	Sertifika doğrulaması nasıl çalışır?	Gateway, TLS handshake sırasında istemci sertifikasını alır, geçerlilik tarihlerini, imzasını ve issuer bilgisini kontrol eder.
Teknik	IP kontrolü zorunlu mu?	Hayır, ancak sertifika paylaşımı riskine karşı özellikle production ortamlarında önerilir.
Kullanım	Farklı endpoint’ler için farklı sertifika politikaları nasıl tanımlanır?	Query Builder’da endpoint bazlı koşullar oluşturup her koşul için ayrı politika atayın.
Kullanım	Varsayılan hata mesajını nasıl değiştirebilirim?	Error Message Customization sekmesinden durum kodu, hata kodu ve mesaj alanlarını düzenleyebilirsiniz.
Genel	mTLS Kimlik Doğrulama Politikası hangi durumlarda kullanılmalı?	Sertifika tabanlı istemci doğrulaması gereken tüm senaryolarda (partner entegrasyonları, kurumsal cihaz erişimleri, yüksek güvenlikli API’ler) kullanılmalıdır.
Genel	Issuer ACL tanımlamazsam ne olur?	Issuer ACL kapalıysa politika tüm geçerli sertifikaları kabul eder; ACL açık ama boşsa tüm istekler reddedilir. Bu nedenle ACL’i gereksinime uygun yönetin.
Teknik	Enable Authorization ne sağlar?	Sertifika doğrulaması sonrası rol ve metod bazlı yetki kontrollerini tetikler; Authorization servisleri veya Secret Manager ile entegre çalışır.
Teknik	IP kontrolü nasıl çalışır?	checkClientIpAddress etkinse istemcinin bağlantı IP’si ACL kayıtlarıyla eşleştirilir; eşleşmeyen istekler 403 döndürür.
Kullanım	Politika değişikliklerini nasıl test etmeliyim?	Test ortamında aynı sertifika zincirini kullanarak mTLS handshake’lerini deneyin, Query Builder koşullarını Postman veya otomasyon testleriyle doğrulayın.
Kullanım	Export edilen ZIP dosyasında hangi bilgiler var?	Politika JSON içeriği, bağımlı Issuer ACL ve hata mesajı yapılandırmaları ile metadata dosyaları bulunur; import sırasında bütünlük kontrolü yapılır.