> ## Documentation Index > Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt > Use this file to discover all available pages before exploring further. # 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?](/tr/concepts/temel-kavramlar/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 mTLS Kimlik Doğrulama Politikası ### 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](/tr/concepts/temel-kavramlar/dinamik-degiskenler) 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?](/tr/concepts/temel-kavramlar/politika-nedir) sayfasındaki [Koşullar](/tr/concepts/temel-kavramlar/politika-nedir#koşullar) ve [Hata Mesajı Özelleştirme (Error Message Customization)](/tr/concepts/temel-kavramlar/politika-nedir#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](/tr/concepts/temel-kavramlar/hata-mesaji-yapilandirma) sayfasına bakın. ## Politikayı Silme Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için [Politika Yönetimi](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi) sayfasındaki [Akıştan Politika Kaldırma](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi#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](/tr/admin/secrets-management/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](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi) sayfasındaki [Politikayı API'ye Bağlama](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi#akisa-politika-ekleme) 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. |