DEV Community

Cover image for Apidog'da İstemci Sertifikası (mTLS) Gerektiren API'ler Nasıl Test Edilir
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Apidog'da İstemci Sertifikası (mTLS) Gerektiren API'ler Nasıl Test Edilir

Bir iş ortağı API'sine geçerli bir token ve iyi biçimlendirilmiş bir istek gönderirsiniz, ancak yine de TLS el sıkışma hatası alırsınız. Uç nokta yalnızca API anahtarınızı istemiyordur: HTTP isteği makinenizden ayrılmadan önce istemcinizin bir sertifika ile kimliğini kanıtlamasını bekliyordur. Bu karşılıklı TLS'tir (mTLS). Bir test aracında ilk kez yapılandırıyorsanız, entegrasyonu saatlerce durdurabilir.

Apidog'u bugün deneyin

Bu kılavuzda, mTLS korumalı bir API'yi el sıkışma ayrıntılarıyla uğraşmadan test etmek için Apidog'da istemci ve CA sertifikalarını yapılandıracaksınız. Belirli bir ana bilgisayar için istemci sertifikası ve anahtar ekleyecek, kendinden imzalı kökler için bir CA sertifikası tanımlayacak ve Apidog'un otomatik olarak imzaladığı bir istek göndereceksiniz. Sertifika hatalarına yeniyseniz, SSL sertifika doğrulaması rehberini de inceleyin. TLS protokolü için MDN TLS referansı satıcıdan bağımsız, sağlam bir kaynaktır.

Karşılıklı TLS nedir ve bazı API'ler neden bunu ister?

Normal HTTPS, tek yönlü güven sağlar:

  1. Sunucu sertifikasını sunar.
  2. İstemci sertifikayı doğrular.
  3. Bağlantı şifrelenir.

Bu akışta sunucu, istemcinin kimliğini kriptografik olarak doğrulamaz. İstemci kimliği genellikle istek içindeki API anahtarı, taşıyıcı token veya OAuth token'ı ile belirlenir.

mTLS ise güveni çift yönlü hale getirir:

  1. Sunucu kendi sertifikasını sunar.
  2. Sunucu, istemcinin de sertifika sunmasını ister.
  3. İstemci sertifikası sunucunun güvendiği bir sertifika yetkilisi (CA) tarafından imzalanmışsa el sıkışma tamamlanır.
  4. Ancak bundan sonra HTTP isteği gönderilir.

İstemci sertifikası geçerli değilse bağlantı hiç açılmaz. İstek gövdesi, başlıklar ve token'lar sunucuya ulaşmaz.

mTLS ile sık karşılaşacağınız durumlar şunlardır:

  • Bankacılık ve ödemeler: Açık bankacılık API'leri ve kart işlemcileri, OAuth'a ek olarak kuruluşa atanmış istemci sertifikası isteyebilir. Stripe belgeleri hassas finansal uç noktalar için bu katmanlı kimlik bilgisi yaklaşımını açıklar.
  • Dahili ve servisler arası trafik: Sıfır güven ağlarında servisler ağ konumuna güvenmek yerine sertifikalarla kimliklerini kanıtlar.
  • B2B iş ortağı API'leri: İş ortakları, yalnızca kayıtlı istemcilerin uç noktalarına erişebilmesi için işe alım sürecinde sertifika sağlayabilir.

OAuth da kullanılıyorsa iki yöntem birlikte çalışır. RFC 8705, mTLS ile OAuth token'larının istemci sertifikalarına nasıl bağlanabileceğini tanımlar.

Buradaki temel ayrım şudur:

Katman Apidog'daki yapılandırma alanı Örnek
TLS kimliği Sertifikalar İstemci sertifikası, CA sertifikası
Uygulama katmanı kimliği Yetkilendirme API anahtarı, Bearer token, OAuth, Basic Auth

Birçok iş ortağı API'si her iki katmanı da gerektirir. Sertifikayı ve token'ı aynı yere eklemeye çalışmayın.

Apidog sertifikaları ana bilgisayara göre nasıl uygular?

Apidog, CA ve istemci sertifikalarını istek bazında değil, global olarak yapılandırır. Sertifikayı bir kez eklersiniz, bir ana bilgisayara bağlarsınız ve Apidog bu ana bilgisayara giden HTTPS isteklerinde sertifikayı otomatik olarak kullanır.

İki sertifika türünün görevi farklıdır:

  • İstemci sertifikası: mTLS sırasında istemci kimliğinizi kanıtlar. İş ortağı API'sinin sizden beklediği sertifikadır.
  • CA sertifikası: Apidog'un henüz tanımadığı bir sertifika yetkilisine güvenmesini sağlar. Dahili kök CA'nızı eklediğinizde SSL Hatası: Kendinden imzalı sertifika hatası ortadan kalkabilir.

Anahtar kavram ana bilgisayar eşleştirmesidir. Her istemci sertifikası belirli bir alan adına bağlanır. Apidog, giden isteğin ana bilgisayarını bu bağlamayla eşleştirir.

Örneğin:

İstemci sertifikası ana bilgisayarı:
partner-api.acmebank.com

İstek URL'si:
https://partner-api.acmebank.com/v1/settlements
Enter fullscreen mode Exit fullscreen mode

Bu eşleşme varsa Apidog sertifikayı TLS el sıkışmasına ekler. Ana bilgisayar yanlışsa Apidog sertifika göndermez.

Bir mTLS API'si için istemci sertifikası kurma

Örnek senaryo:

  • İş ortağı API'si: partner-api.acmebank.com
  • Uç nokta: GET /v1/settlements
  • Kimlik bilgileri:
    • İstemci sertifikası
    • Özel anahtar
    • OAuth Bearer token

Adım 1: Sertifikalar ayarlarını açın

Apidog'da sağ üstteki ayarlar simgesini açın ve Sertifikalar sekmesine gidin.

Buradaki yapılandırmalar tek bir isteğe bağlı değildir. Ana bilgisayar eşleşmesine göre tüm isteklerde uygulanır.

Adım 2: İstemci sertifikasını ekleyin

İstemci Sertifikaları bölümünde Sertifika Ekle seçeneğini seçin.

Ana Bilgisayar alanına yalnızca alan adını girin:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

https:// eklemeyin. Bu alan yalnızca ana bilgisayar adını kabul eder.

Birden fazla alt alan adı aynı sertifikayı kullanıyorsa desen eşleştirme kullanabilirsiniz:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Bu yapılandırma aşağıdaki hedeflerde aynı istemci sertifikasını kullanır:

partner-api.acmebank.com
sandbox-api.acmebank.com
settlements-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Özel bağlantı noktası kullanmıyorsanız bağlantı noktası alanını boş bırakın. Varsayılan HTTPS bağlantı noktası 443 olarak kullanılır.

API farklı bir bağlantı noktasında dinliyorsa bunu açıkça tanımlayın:

Host: partner-api.acmebank.com
Port: 8443
Enter fullscreen mode Exit fullscreen mode

Adım 3: Sertifika dosyalarını seçin

Apidog istemci sertifikaları için iki dosya düzenini destekler:

  • CRT + Anahtar: Ayrı sertifika ve özel anahtar dosyaları.
  • PFX: Sertifika ve anahtarı tek dosyada içeren paket.

İş ortağınızın sağladığı formata göre seçim yapın.

Örnek CRT ve anahtar dosyaları:

client.crt
client.key
Enter fullscreen mode Exit fullscreen mode

Örnek PFX dosyası:

client.pfx
Enter fullscreen mode Exit fullscreen mode

Özel anahtar veya PFX dosyası parola korumalıysa Parola alanına parolayı girin. Parola yoksa alanı boş bırakın.

Adım 4: Sertifikayı kaydedin

Ekle seçeneğine tıklayın.

Sertifika listesinde aşağıdakine benzer bir kayıt görmelisiniz:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Bu noktadan sonra her istek için sertifikayı tekrar seçmeniz gerekmez.

Adım 5: Kimliği doğrulanmış isteği gönderin

Yeni bir istek oluşturun:

GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>
Enter fullscreen mode Exit fullscreen mode

Apidog şu işlemleri otomatik olarak yapar:

  1. İstek URL'sindeki ana bilgisayarı algılar.
  2. partner-api.acmebank.com için tanımlanan istemci sertifikasını bulur.
  3. TLS el sıkışması sırasında istemci sertifikasını sunar.
  4. mTLS doğrulaması tamamlandıktan sonra HTTP isteğini gönderir.
  5. Bearer token'ı normal HTTP yetkilendirme bilgisi olarak iletir.

Başarılı yanıt örneği:

{
  "settlements": [
    {
      "id": "stl_88213",
      "amount": 41200,
      "currency": "USD",
      "status": "cleared",
      "settled_at": "2026-07-14T09:31:00Z"
    }
  ],
  "next_cursor": null
}
Enter fullscreen mode Exit fullscreen mode

Dahili veya kendinden imzalı kökler için CA sertifikası ekleyin

İstemci sertifikası, sunucuya kim olduğunuzu kanıtlar. Ancak sunucunun sertifikası makinenizin güvenmediği bir CA tarafından imzalanmışsa bağlantı daha mTLS aşamasına ulaşmadan başarısız olabilir.

Bu durum özellikle şuralarda yaygındır:

  • Dahili servisler
  • Hazırlık ortamları
  • Özel PKI altyapıları
  • Kendinden imzalı sertifika kullanan sistemler

Tipik hata:

SSL Hatası: Kendinden imzalı sertifika
Enter fullscreen mode Exit fullscreen mode

Çözüm, ilgili CA sertifikasını Apidog'a eklemektir.

  1. Sertifikalar sekmesini açın.
  2. CA Sertifikaları anahtarını etkinleştirin.
  3. PEM biçimindeki CA dosyanızı seçin.

CA sertifikaları PEM formatında kullanılır. Tek bir PEM dosyasında birden fazla sertifika bulunabilir:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
Enter fullscreen mode Exit fullscreen mode

Bu yapılandırmada:

  • CA sertifikası, Apidog'un sunucu sertifikasına güvenmesini sağlar.
  • İstemci sertifikası, sunucunun istemcinize güvenmesini sağlar.

Özel kök CA kullanan dahili bir mTLS servisini test etmek için çoğu zaman ikisine de ihtiyacınız olur.

Gelişmiş ipuçları ve yaygın varyasyonlar

Tek sertifika ile alt alan adı kapsamı

İş ortağı genel kapsamlı bir sertifika sağladıysa her alt alan adını tek tek eklemeyin.

Şunu kullanın:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Böylece aynı sertifika birden fazla API ana bilgisayarında uygulanır.

Standart olmayan bağlantı noktaları

Dahili mTLS ağ geçitleri sıkça 8443 veya 9443 gibi bağlantı noktalarında çalışır.

Örnek:

https://gateway.internal.example.com:8443/api/health
Enter fullscreen mode Exit fullscreen mode

Sertifika yapılandırmasında bağlantı noktasını da 8443 olarak tanımlayın. Aksi halde ana bilgisayar eşleşmesi gerçekleşmeyebilir ve sertifika gönderilmez.

Sertifikalar eklendikten sonra düzenlenemez

Mevcut sertifikayı yerinde güncelleme seçeneği yoktur. Sertifika yenilemek veya ana bilgisayar adındaki yazım hatasını düzeltmek için:

  1. Eski sertifikayı silin.
  2. Güncel sertifikayı yeniden ekleyin.

Bu adımı sertifika rotasyon prosedürünüze ekleyin.

Etki alanı başına tek sertifika kullanın

Aynı etki alanına birden fazla istemci sertifikası eklemeyin.

Örneğin, aşağıdaki yapılandırmadan kaçının:

partner-api.acmebank.com -> client-v1.crt
partner-api.acmebank.com -> client-v2.crt
Enter fullscreen mode Exit fullscreen mode

Bir ana bilgisayar için tek, aktif sertifika tutun. Yenileme sırasında eski kaydı kaldırıp yeni kaydı ekleyin.

Sertifikaları ve Yetkilendirmeyi ayrı yapılandırın

mTLS için:

Sertifikalar > İstemci Sertifikaları
Enter fullscreen mode Exit fullscreen mode

API anahtarı, Bearer token, OAuth veya Basic Auth için:

İstek/Klasör/Koleksiyon > Yetkilendirme
Enter fullscreen mode Exit fullscreen mode

Yetkilendirme ayarları üç seviyede uygulanabilir:

  • Tekil istek
  • Klasör
  • Koleksiyon

Örneğin bir iş ortağı hem mTLS hem OAuth istiyorsa:

İstemci sertifikası -> Sertifikalar
OAuth token -> Yetkilendirme
Enter fullscreen mode Exit fullscreen mode

Bu yapılandırmalar birbirinin yerine geçmez; birlikte çalışır.

Token tabanlı kimlik doğrulama için API ağ geçidi kimlik doğrulaması rehberine bakın. Windows ağırlıklı ortamlarda çalışan ekipler için Apidog'da Kerberos kimlik doğrulamasını yapılandırma rehberi de yararlıdır.

Yalnızca HTTPS kullanın

Apidog düz HTTP isteklerine istemci sertifikası eklemez.

Bu istek mTLS çalıştırmaz:

http://partner-api.acmebank.com/v1/settlements
Enter fullscreen mode Exit fullscreen mode

Bu istek çalışır:

https://partner-api.acmebank.com/v1/settlements
Enter fullscreen mode Exit fullscreen mode

mTLS'nin devreye girmesi için uç noktanın HTTPS kullanması zorunludur.

İş akışını Apidog CLI ile otomatikleştirin

mTLS isteğiniz Apidog arayüzünde çalıştıktan sonra bunu kaydedilmiş test senaryolarına ekleyebilir ve Apidog CLI ile başsız olarak çalıştırabilirsiniz.

Önce CLI'yi kurun ve kimlik doğrulaması yapın:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Ardından kaydedilmiş bir senaryoyu belirli ortamda çalıştırın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

apidog run ile istemci sertifikası ayarlarını doğrudan geçebilirsiniz:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  --ssl-client-cert ./client.pem \
  --ssl-client-key ./client.key \
  --ssl-client-passphrase "$CLIENT_CERT_PASSPHRASE" \
  --ssl-extra-ca-certs ./internal-ca.pem \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

Kullanılabilecek ilgili parametreler:

Parametre Amaç
--ssl-client-cert PEM istemci sertifikası
--ssl-client-key Özel anahtar
--ssl-client-passphrase Anahtar parolası
--ssl-extra-ca-certs Ek güvenilir CA sertifikaları
--ssl-client-cert-list URL desenine göre sertifika eşleştirme yapılandırması
-r html,cli HTML ve CLI raporları

Bu komutu CI/CD işinize ekleyerek sertifika korumalı API'lerinizi her itmede test edebilirsiniz. Daha fazla ayrıntı için CI/CD'de Apidog CLI rehberini inceleyin.

Sıkça sorulan sorular

Bir istemci sertifikasına ve bir CA sertifikasına mı, yoksa yalnızca birine mi ihtiyacım var?

Uç noktaya bağlıdır.

  • Sunucu mTLS istiyorsa istemci sertifikasına ihtiyacınız vardır.
  • Sunucunun sertifikası güvenilmeyen özel veya dahili bir CA tarafından imzalanmışsa CA sertifikasına da ihtiyacınız vardır.

Genel olarak güvenilen bir CA kullanan iş ortağı API'sinde yalnızca istemci sertifikası yeterli olabilir. Özel kök CA kullanan dahili mTLS servislerinde genellikle her iki sertifika gerekir.

Apidog neden istemci sertifikamı göndermiyor?

En yaygın nedenler:

  1. Ana bilgisayar eşleşmiyordur.
  2. Ana bilgisayar alanına https:// eklenmiştir.
  3. Bağlantı noktası farklıdır.
  4. İstek HTTP kullanıyordur.

Kontrol listesi:

[ ] Ana bilgisayar tam alan adı mı?
[ ] Ana bilgisayar alanında https:// yok mu?
[ ] Özel bağlantı noktası doğru mu?
[ ] İstek URL'si https:// ile mi başlıyor?
Enter fullscreen mode Exit fullscreen mode

Apidog HTTP isteklerine hiçbir zaman istemci sertifikası eklemez.

API anahtarları ve taşıyıcı token'lar nereye gider?

Bunları Sertifikalar bölümüne değil, isteğin veya klasörün Yetkilendirme sekmesine ekleyin.

  • Sertifikalar: TLS katmanı kimliği
  • Yetkilendirme: API Key, Bearer Token, OAuth, Basic Auth

Kimlik doğrulama türleri hakkında daha fazla bilgi için güvenlik şemaları rehberini inceleyin.

Bir sertifika birden fazla alt alanı kapsayabilir mi?

Evet. Ana bilgisayar alanında desen eşleştirme kullanın:

*.example.com
Enter fullscreen mode Exit fullscreen mode

Bu tanım, example.com altındaki alt alan adları için aynı istemci sertifikasını kullanır.

Bir sertifikayı eklendikten sonra nasıl güncellerim?

Sertifikalar yerinde düzenlenemez.

  1. Mevcut sertifikayı silin.
  2. Düzeltilmiş veya yenilenmiş sertifikayı ekleyin.

Sertifika rotasyonlarında ortam değişkenlerini düzenli tutmak için Apidog'da genel parametreler ayarlama rehberini kullanabilirsiniz.

Özet

mTLS korumalı bir API'yi Apidog ile test etmek için:

  1. İstemci sertifikasını doğru ana bilgisayara bağlayın.
  2. Sunucu özel veya kendinden imzalı bir kök kullanıyorsa CA sertifikasını ekleyin.
  3. İstek URL'sinin HTTPS kullandığından emin olun.
  4. OAuth veya API anahtarı gibi uygulama katmanı kimlik bilgilerini Yetkilendirme sekmesinde yapılandırın.
  5. Ana bilgisayar eşleştirmesinin sertifikayı her istekte otomatik olarak uygulamasına izin verin.

İş ortağınızın sertifikasını eklemek ve ilk kimliği doğrulanmış isteğinizi göndermek için Apidog'u indirin. Ücretsiz deneyin, kredi kartı gerekmez.

Top comments (0)