Bir iş ortağı API'sine istek gönderirsiniz, geçerli bir token ile iyi biçimlendirilmiş bir istek gönderirsiniz ve yine de bir TLS el sıkışma hatasıyla karşılaşırsınız. Uç nokta API anahtarınızı istemiyor. HTTP isteği makinenizden ayrılmadan önce istemcinizden bir sertifika ile kim olduğunu kanıtlamasını istiyor. İşte bu karşılıklı TLS'dir ve bunu bir test aracında hiç yapılandırmadıysanız, bir entegrasyonu bir günlüğüne durdurabilir.
Bu kılavuz, el sıkışma ile uğraşmadan bir mTLS korumalı API'yi test edebilmeniz için Apidog'da istemci sertifikalarını ve CA sertifikalarını nasıl kuracağınızı anlatır. Belirli bir ana bilgisayar için bir istemci sertifikası ve anahtarı ekleyecek, kendi kendine imzalanmış köklerin hata vermesini durdurmak için bir CA sertifikası ekleyecek ve Apidog'un otomatik olarak imzaladığı kimliği doğrulanmış bir istek göndereceksiniz. Sertifika hataları sizin için yeni bir alan ise, SSL sertifika doğrulaması üzerine olan giriş yazısı bu yazıyla birlikte okunmaya değerdir. Protokolün kendisi için, MDN TLS referansı sağlam, satıcıdan bağımsız bir açıklayıcıdır.
Karşılıklı TLS nedir ve bazı API'ler neden bunu ister?
Normal HTTPS tek yönlü güvendir. Sunucu bir sertifika sunar, istemciniz bunu doğrular ve bağlantı şifrelenir. Sunucunun kim olduğunuzla ilgili kriptografik bir kanıtı yoktur; bunun için isteğin içindeki bir tokene veya API anahtarına güvenir.
Karşılıklı TLS güveni iki yönlü hale getirir. Sunucu hala kendi sertifikasını sunar, ancak aynı zamanda istemciden de bir tane sunmasını ister. Sertifikanız sunucunun güvendiği bir sertifika yetkilisi tarafından imzalanmamışsa, el sıkışma başarısız olur ve bağlantı asla açılmaz. İstek gövdesi yok, başlık yok, hiçbir şey geçmez.
Sızdırılmış bir taşıyıcı token'ın kabul edilebilir bir hata modu olmadığı yerlerde karşılıklı TLS (mTLS) kimlik doğrulaması ile karşılaşacaksınız:
- Bankacılık ve ödemeler. Açık bankacılık API'leri ve kart işlemcileri genellikle OAuth'a ek olarak kuruluşunuza verilmiş bir istemci sertifikası gerektirir. Stripe belgeleri hassas finansal uç noktalar için bu tür katmanlı kimlik bilgisi modelini açıklar.
- Dahili ve hizmetler arası trafik. Sıfır güven ağı çalıştıran şirketler, ağ çevresine güvenmek yerine hizmetlerin kimliklerini sertifikalarla kanıtlamasını sağlar.
- B2B iş ortağı API'leri. Bir iş ortağı, işe alım sırasında size bir istemci sertifikası verebilir, böylece yalnızca kayıtlı makineleriniz onların uç noktalarına ulaşabilir.
OAuth da devredeyse, ikisi temiz bir şekilde birleşir; RFC 8705, karşılıklı TLS'nin bir OAuth token'ını bir istemci sertifikasına nasıl bağladığını resmiyete kavuşturur. Sertifika, isteğinizdeki uygulama katmanı kimlik doğrulamasından ayrı, bir ağ katmanı kimlik bilgisidir. Bu ayrım Apidog'da önemlidir ve insanların en çok karıştığı şeydir. Sertifikalar mTLS'yi halleder. Yetkilendirme sekmesi API anahtarlarını, taşıyıcı tokenları, OAuth'ı ve Temel kimlik doğrulamasını halleder. Genellikle ikisine birden ihtiyacınız olur, ancak bunları farklı yerlerde yapılandırırsınız.
Apidog sertifikaları ana bilgisayara göre nasıl kapsar?
Apidog hem CA sertifikalarını hem de istemci sertifikalarını yönetir ve bunları istek başına değil, global olarak yapılandırır. Bir sertifikayı bir kez kurar, bir ana bilgisayara bağlar ve Apidog, o ana bilgisayarla eşleşen her HTTPS isteğine otomatik olarak ekler. Hatırlanacak istek başına bir geçiş düğmesi veya yapıştırılacak bir başlık yoktur.
İki sertifika türü iki farklı iş yapar:
- Bir istemci sertifikası, karşılıklı TLS kimlik doğrulaması için kimliğinizi kanıtlamak üzere sunduğunuz şeydir. İş ortağı API'sinin istediği kimlik bilgisidir.
- Bir CA sertifikası, Apidog'a henüz bilmediği bir sertifika yetkilisine güvenmesini söyler. Bunu dahili kök CA'nıza yönlendirin ve korkulan
SSL Hatası: Kendinden imzalı sertifikaortadan kalkar, çünkü Apidog artık o yetkili tarafından imzalanan uç noktalara güvenir.
Kapsam belirleme anahtarı ana bilgisayardır. Her istemci sertifikası bir etki alanına bağlıdır ve Apidog, giden isteğin ana bilgisayarını bu bağlamayla eşleştirir. Ana bilgisayarı doğru ayarlayın ve gerisi otomatikleşir. Yanlış ayarlarsanız, Apidog sessizce hiçbir şey göndermez, çünkü eşleşme bulamamıştır.
Bir mTLS API'si için istemci sertifikası kurma
İşte senaryo. Bir ödeme iş ortağı, partner-api.acmebank.com, işe alım sırasında size bir istemci sertifikası ve özel anahtar verdi. API'leri yalnızca HTTPS'dir ve bu sertifikayı sunamayan herhangi bir istemciyi reddeder. GET /v1/settlements çağrısı yapmak ve yanıtı incelemek istiyorsunuz.
Adım 1: Sertifikalar ayarlarını açın
Sağ üstteki ayarlar simgesini kullanarak Apidog ayarlarını açın, ardından Sertifikalar sekmesine gidin. Her iki sertifika türü de buradadır. Buradaki hiçbir şey tek bir isteğe bağlı değildir; ana bilgisayar eşleştirmesine göre istekleriniz arasında uygulanır.
Adım 2: İstemci sertifikasını ekleyin
İstemci Sertifikaları altında, Sertifika Ekle'yi seçin. Ana bilgisayar bağlaması ve sertifika dosyaları için bir form açılır.
Ana Bilgisayar alanını yalnızca etki alanı ile doldurun, protokol olmadan:
partner-api.acmebank.com
https:// kısmını atlayın. Alan yalnızca bir etki alanı alır. Birden fazla alt etki alanını kapsayacak tek bir sertifikaya ihtiyacınız varsa, ana bilgisayar alanı desen eşleştirmeyi destekler. *.acmebank.com girmek, acmebank.com altındaki her alt etki alanı için aynı istemci sertifikasını kullanır; bu, bir iş ortağının aynı verilen sertifikadan partner-api, sandbox-api ve settlements-api çalıştırdığı durumlarda kullanışlıdır.
Özel bağlantı noktası isteğe bağlıdır. Boş bırakın, Apidog varsayılan olarak standart HTTPS bağlantı noktası olan 443'ü kullanır. Bir bağlantı noktası yalnızca mTLS uç noktası başka bir yerde, örneğin 8443'te dinliyorsa ayarlayın.
Adım 3: Sertifika dosyalarını seçin
Apidog, bir istemci sertifikası için iki dosya düzenini kabul eder. İş ortağınızın size verdiğini seçin:
- CRT + Anahtar dosyaları. Ayrı bir sertifika dosyası ve özel anahtar dosyası. Her birini kendi alanında seçin.
- PFX dosyaları. Sertifika ve anahtarı bir arada içeren tek bir paketlenmiş dosya.
Sertifika bir parola ile oluşturulduysa, bunu parola alanına girin. İsteğe bağlıdır, bu nedenle anahtarınız parola korumalı değilse boş bırakın. Bir bankadan tipik bir işe alım paketi, bazen anahtarda bir parola ile birlikte bir .crt ve bir .key çifti olarak gelir.
Adım 4: Kaydedin
İstemci sertifikasını kaydetmek için Ekle'yi seçin. Artık listenizde, partner-api.acmebank.com'a bağlı olarak görünür. Bu noktadan sonra istek başına bir daha dokunmazsınız.
Adım 5: Kimliği doğrulanmış isteği gönderin
Ana bilgisayara bir istek oluşturun ve gönderin:
GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>
Apidog ana bilgisayarı eşleştirir, TLS el sıkışması sırasında istemci sertifikanızı ekler ve istek gönderilmeden önce karşılıklı TLS kimlik doğrulamasını tamamlar. İş ortağı OAuth da gerektiriyorsa, bu taşıyıcı token her zamanki gibi istekte yer alır. Sertifika makineyi, token ise çağrı yapanı kanıtlar. Başarılı bir yanıt şöyle görünebilir:
{
"settlements": [
{
"id": "stl_88213",
"amount": 41200,
"currency": "USD",
"status": "cleared",
"settled_at": "2026-07-14T09:31:00Z"
}
],
"next_cursor": null
}
Bunu manuel, istek başına bir adım değil, ana bilgisayar eşleşmesi sağladı.
Dahili veya kendinden imzalı kökler için bir CA sertifikası ekleyin
İstemci sertifikaları hikayenin yarısıdır. Diğer yarısı, sunucunun kendi sertifikası, makinenizin güvenmediği bir yetkili tarafından imzalandığında ortaya çıkar; bu durum, özel bir kök CA kullanan dahili hizmetler ve hazırlık ortamlarında yaygındır.
Bu olduğunda, mTLS bir şans bile bulamadan istek SSL Hatası: Kendinden imzalı sertifika gibi bir mesajla başarısız olur. Çözüm, Apidog'a CA'yı vermek, böylece o köke güvenmesini sağlamaktır.
Aynı Sertifikalar sekmesinde, CA Sertifikaları'nın yanındaki anahtarı açın, ardından PEM dosyanızı seçin. CA sertifikaları PEM formatını kullanır ve tek bir PEM dosyası birden fazla CA sertifikası içerebilir, böylece tüm bir dahili kök ve ara sertifika zincirini tek bir dosyada toplayabilirsiniz:
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
CA'ya güvenildiğinde, Apidog tarafından imzalanan uç noktaları reddetmeyi durdurur. Güvenilen bir CA'yı bir istemci sertifikasıyla eşleştirin ve özel bir kök kullanan dahili bir mTLS hizmetini uçtan uca test edebilirsiniz: CA onların sunucusuna güvenmenizi sağlar ve istemci sertifikası onların size güvenmesini sağlar.
Gelişmiş ipuçları ve yaygın varyasyonlar
Temel kurulumu tamamladığınızda birkaç şey zamandan tasarruf ettirir.
Tek bir sertifika ile alt alan adı kapsamı. Bir iş ortağı genel kapsamlı bir sertifika verdiyse, partner-api, sandbox-api ve diğerlerini ayrı ayrı kaydetmek yerine ana bilgisayarı bir kez *.acmebank.com olarak ayarlayın. Tek bir bağlama, her alt alan adı.
Standart olmayan bağlantı noktaları. Dahili mTLS ağ geçitleri 8443 veya 9443 gibi bağlantı noktalarını sever. Varsayılan 443'tür, bu nedenle uç nokta başka bir yerde dinliyorsa her zaman özel bağlantı noktasını belirtin, aksi takdirde ana bilgisayar eşleşmez ve hiçbir sertifika gönderilmez.
Sertifikalar eklendikten sonra düzenlenemez. Düzenleme eylemi yoktur. Yenilenmiş bir sertifikayı döndürmek veya ana bilgisayardaki bir yazım hatasını düzeltmek için, mevcut olanı silme simgesiyle kaldırın ve tekrar ekleyin. Bunu sertifika döndürme kılavuzunuza dahil edin, böylece kimse orada olmayan bir düzenle düğmesi aramaz.
Etki alanı başına bir sertifika. Aynı etki alanı için iki istemci sertifikası kaydetmeyin. Her bağlama etki alanına özeldir ve bir kopya Apidog'un hangisini sunması gerektiği konusunda belirsizlik yaratır. Ana bilgisayar başına bir tane tutun.
Sertifikaları ve Yetkilendirmeyi kafanızda ayrı tutun. Bu en büyük karışıklık kaynağıdır. mTLS, Sertifikalar sekmesinde bulunur. API anahtarları, taşıyıcı tokenlar, OAuth ve Temel kimlik doğrulaması, bir isteğin veya klasörün Yetkilendirme sekmesinde bulunur ve istekler yetkilendirmeyi üst klasörlerinden miras alır. Yetkilendirme üç düzeyde uygulanır: bireysel istekler, bir klasördeki tüm istekler ve bir koleksiyondaki tüm istekler. Bir iş ortağı hem istemci sertifikası hem de OAuth gerektiriyorsa, sertifikayı Sertifikalar'a ve token'ı Yetkilendirme'ye ayarlarsınız. Bunlar çakışmaz. Token tabanlı kimlik doğrulamasını yapılandırmaya daha derin bir bakış için, API ağ geçidi kimlik doğrulaması kılavuzu istek tarafını kapsar ve Windows ağırlıklı bir yığınla uğraşıyorsanız, Apidog'da Kerberos kimlik doğrulamasını yapılandırma, yer imlerine eklemeye değer benzer bir rehberdir.
Yalnızca HTTPS, her zaman. Apidog, düz bir HTTP isteğine istemci sertifikası eklemez. Test hedefiniz http:// ise, sertifika asla gönderilmez ve el sıkışma mantığı asla çalışmaz. Bunların herhangi birinin uygulanabilmesi için uç noktanın HTTPS olması gerekir.
İş akışını Apidog CLI ile otomatikleştirin
mTLS istekleriniz manuel olarak geçtikten sonra, bunları kaydedilmiş test senaryolarına dahil edin ve Apidog CLI ile başsız bir şekilde çalıştırın. Kurun ve kimlik doğrulayın:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Ardından, kaydedilmiş bir senaryoyu bir ortama karşı çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
apidog run komutu doğrudan istemci sertifikası yapılandırmasını destekler, böylece mTLS, GUI'den işlem hattına geçişte hayatta kalır. Tek bir sertifika için, --ssl-client-cert (PEM sertifikası), --ssl-client-key (özel anahtar) ve anahtarın varsa --ssl-client-passphrase'i geçirin. Ek güvenilir CA'ları --ssl-extra-ca-certs ile işaretleyin veya URL desenine göre sertifikaları ana bilgisayarlarla eşleştirdiğinizde bir yapılandırma dosyasıyla --ssl-client-cert-list kullanın. Raporlayıcılar -r ile ayarlanır (-r html,cli'yi deneyin). Bu komutu bir işe bağlayın ve sertifika korumalı API'niz her itmede test edilir. CI/CD'de Apidog CLI kılavuzu, bunu bir işlem hattı içinde çalıştırmayı kapsar.
Sıkça sorulan sorular
Bir istemci sertifikasına ve bir CA sertifikasına mı yoksa sadece birine mi ihtiyacım var?
Uç noktaya bağlıdır. Bir istemci sertifikası kimliğinizi kanıtlar, bu nedenle sunucu karşılıklı TLS talep ettiğinde ona ihtiyacınız vardır. Bir CA sertifikası yalnızca sunucunun kendi sertifikası, makinenizin henüz güvenmediği bir yetkili (dahili bir kök CA gibi) tarafından imzalandığında gereklidir. Güvenilir bir genel CA üzerindeki halka açık bir iş ortağı API'si yalnızca istemci sertifikasına ihtiyaç duyar; özel bir kök üzerindeki dahili bir mTLS hizmeti genellikle her ikisine de ihtiyaç duyar.
Apidog neden istemci sertifikamı göndermiyor?
Neredeyse her zaman ana bilgisayar eşleşmeme hatası veya düz bir HTTP hedefi. Ana Bilgisayar alanının https:// öneki olmadan tam etki alanını içerdiğini, bağlantı noktasının eşleştiğini (varsayılan 443, bu nedenle uç nokta başka bir yerde dinliyorsa özel bir bağlantı noktası ayarlayın) ve istek URL'sinin HTTPS olduğunu kontrol edin. Apidog asla bir HTTP isteğine sertifika eklemez.
API anahtarları ve taşıyıcı tokenlar Sertifikalar'da değilse nereye gider?
Sertifika kurulumundan ayrı olan isteğin veya klasörün Yetkilendirme sekmesinde bulunur. Sertifikalar TLS katmanı kimliğini yönetir; Yetkilendirme, istek katmanında API Anahtarı, Taşıyıcı Token, OAuth ve Temel kimlik doğrulamasını yönetir. Kimlik doğrulama türlerinin tam dökümünü güvenlik şemaları kılavuzunda bulabilirsiniz ve her isteğin miras alması için yetkilendirmeyi bir kez klasör veya koleksiyon düzeyinde ayarlayabilirsiniz.
Bir sertifika birden fazla alt alanı kapsayabilir mi?
Evet. Ana bilgisayar alanı desen eşleştirmeyi destekler. *.example.com girin ve aynı istemci sertifikası example.com'un her alt alanı için geçerli olur. Bu, bir iş ortağının birkaç API alt alanı için verdiği genel kapsamlı bir sertifikayı yeniden kullanmanın temiz bir yoludur.
Bir sertifikayı eklendikten sonra nasıl güncellerim?
Sertifikalar yerinde düzenlenemez. Mevcut olanı silme simgesiyle kaldırın, ardından düzeltilmiş veya yenilenmiş sürümü ekleyin. Bunu sertifika döndürme için aklınızda bulundurun ve test kurulumlarını düzenlerken, Apidog'da genel parametreler ayarlama, çevre değerlerini istekler arasında düzenli tutmak için iyi bir eşleşmedir.
Özetleme
mTLS korumalı bir API'yi test etmek Apidog'da üç adıma iner: bir istemci sertifikasını doğru ana bilgisayara bağlayın, sunucu özel bir kök kullanıyorsa bir CA sertifikası ekleyin ve ana bilgisayar eşleştirmesinin her HTTPS isteğini otomatik olarak imzalamasına izin verin. Sertifikaları ve Yetkilendirmeyi ayrı tutun ve el sıkışması bir sır olmaktan çıkar.
Beraber ilerlemek, iş ortağınızın sertifikasını eklemek ve ilk kimliği doğrulanmış isteği göndermek için Apidog'u indirin. Ücretsiz deneyin, kredi kartı gerekmez.