Cara Menguji API dengan Sertifikat Klien (mTLS) di Apidog

Anda mengakses API mitra, mengirim permintaan yang terstruktur dengan baik dengan token yang valid, namun masih mendapatkan kegagalan jabat tangan TLS. Endpoint tersebut tidak meminta kunci API Anda. Endpoint tersebut meminta klien Anda untuk membuktikan identitasnya dengan sertifikat, bahkan sebelum permintaan HTTP apa pun meninggalkan mesin Anda. Itu adalah mutual TLS, dan jika Anda belum pernah mengonfigurasinya di alat pengujian, hal ini dapat menunda integrasi selama sehari.

Panduan ini akan membahas pengaturan sertifikat klien dan sertifikat CA di Apidog agar Anda dapat menguji API yang dilindungi mTLS tanpa kesulitan dalam jabat tangan. Anda akan menambahkan sertifikat dan kunci klien untuk host tertentu, melampirkan sertifikat CA agar root yang ditandatangani sendiri tidak lagi menimbulkan kesalahan, dan mengirim permintaan terautentikasi yang ditandatangani Apidog secara otomatis. Jika kesalahan sertifikat adalah hal baru bagi Anda, panduan dasar tentang verifikasi sertifikat SSL layak dibaca bersama panduan ini. Untuk protokolnya sendiri, referensi TLS MDN adalah penjelasan yang solid dan netral vendor.

tombol

Apa itu mutual TLS dan mengapa beberapa API memerlukannya

HTTPS biasa adalah kepercayaan satu arah. Server menyajikan sertifikat, klien Anda memverifikasinya, dan koneksi dienkripsi. Server tidak memiliki bukti kriptografi tentang siapa Anda; itu mengandalkan token atau kunci API di dalam permintaan untuk itu.

Mutual TLS membuat kepercayaan berjalan dua arah. Server masih menyajikan sertifikatnya, tetapi juga meminta klien untuk menyajikan satu sertifikat. Jika sertifikat Anda tidak ditandatangani oleh otoritas sertifikat yang dipercaya server, jabat tangan gagal dan koneksi tidak pernah terbuka. Tidak ada badan permintaan, tidak ada header, tidak ada yang bisa melewati.

Anda akan menemukan autentikasi mutual TLS (mTLS) di tempat-tempat di mana token pembawa yang bocor bukanlah mode kegagalan yang dapat diterima:

Perbankan dan pembayaran. API open-banking dan pemroses kartu seringkali memerlukan sertifikat klien yang dikeluarkan untuk organisasi Anda di atas OAuth. Dokumentasi Stripe menjelaskan model kredensial berlapis semacam ini untuk endpoint keuangan yang sensitif.
Lalu lintas internal dan layanan-ke-layanan. Perusahaan yang menjalankan jaringan zero-trust membuat layanan membuktikan identitas dengan sertifikat alih-alih mempercayai perimeter jaringan.
API mitra B2B. Seorang mitra dapat mengeluarkan sertifikat klien kepada Anda selama proses orientasi sehingga hanya mesin terdaftar Anda yang dapat mencapai endpoint mereka.

Jika OAuth juga digunakan, keduanya bergabung dengan rapi; RFC 8705 memformalkan bagaimana mutual-TLS mengikat token OAuth ke sertifikat klien. Sertifikat adalah kredensial lapisan jaringan, terpisah dari autentikasi lapisan aplikasi dalam permintaan Anda. Perbedaan itu penting di Apidog, dan seringkali menjadi penyebab kebingungan. Sertifikat menangani mTLS. Tab Otorisasi menangani kunci API, token pembawa, OAuth, dan autentikasi Dasar. Anda sering membutuhkan keduanya sekaligus, tetapi Anda mengonfigurasinya di tempat yang berbeda.

Bagaimana Apidog menargetkan sertifikat berdasarkan host

Apidog menangani sertifikat CA dan sertifikat klien, dan mengonfigurasinya secara global daripada per permintaan. Anda mengatur sertifikat sekali, mengikatnya ke host, dan Apidog melampirkannya secara otomatis pada setiap permintaan HTTPS yang cocok dengan host tersebut. Tidak ada tombol per permintaan yang perlu diingat dan tidak ada header yang perlu ditempel.

Dua jenis sertifikat melakukan dua pekerjaan berbeda:

Sebuah sertifikat klien adalah apa yang Anda sajikan untuk membuktikan identitas Anda untuk autentikasi mutual TLS. Ini adalah kredensial yang diminta oleh API mitra.
Sebuah sertifikat CA memberitahu Apidog untuk mempercayai otoritas sertifikat yang belum dikenalnya. Arahkan ke root CA internal Anda dan pesan SSL Error: Self signed certificate yang ditakuti akan hilang, karena Apidog sekarang mempercayai endpoint yang ditandatangani oleh otoritas tersebut.

Kunci penargetan adalah host. Setiap sertifikat klien terikat pada suatu domain, dan Apidog mencocokkan host permintaan keluar dengan ikatan tersebut. Jika host benar, yang lainnya otomatis. Jika salah, Apidog diam-diam tidak mengirim apa-apa, karena tidak pernah menemukan kecocokan.

Menyiapkan sertifikat klien untuk API mTLS

Berikut adalah skenarionya. Mitra pembayaran, partner-api.acmebank.com, mengeluarkan sertifikat klien dan kunci privat kepada Anda selama proses orientasi. API mereka hanya HTTPS dan menolak klien mana pun yang tidak dapat menyajikan sertifikat tersebut. Anda ingin memanggil GET /v1/settlements dan memeriksa responsnya.

Langkah 1: Buka pengaturan Sertifikat

Buka pengaturan Apidog menggunakan ikon pengaturan di kanan atas, lalu buka tab Sertifikat. Di sinilah kedua jenis sertifikat berada. Tidak ada di sini yang terikat pada satu permintaan; ini berlaku di seluruh permintaan Anda berdasarkan pencocokan host.

Langkah 2: Tambahkan sertifikat klien

Di bawah Sertifikat Klien, pilih Tambah Sertifikat. Sebuah formulir terbuka untuk pengikatan host dan file sertifikat.

Isi kolom Host hanya dengan domain, tanpa protokol:

partner-api.acmebank.com

Jangan sertakan https://. Kolom tersebut hanya menerima domain mentah. Jika Anda memerlukan satu sertifikat untuk mencakup beberapa subdomain, kolom host mendukung pencocokan pola. Memasukkan *.acmebank.com menggunakan sertifikat klien yang sama untuk setiap subdomain di bawah acmebank.com, yang berguna ketika mitra menjalankan partner-api, sandbox-api, dan settlements-api dari sertifikat yang sama.

Port kustom bersifat opsional. Biarkan kosong dan Apidog akan menggunakan default 443, port HTTPS standar. Atur port hanya jika endpoint mTLS mendengarkan di tempat lain, misalnya 8443.

Langkah 3: Pilih file sertifikat

Apidog menerima dua tata letak file untuk sertifikat klien. Pilih salah satu yang diberikan mitra Anda:

File CRT + Kunci. File sertifikat terpisah dan file kunci privat. Pilih masing-masing di kolomnya.
File PFX. Satu file gabungan yang mengemas sertifikat dan kunci secara bersamaan.

Jika sertifikat dibuat dengan frasa sandi, masukkan di kolom frasa sandi. Ini opsional, jadi biarkan kosong jika kunci Anda tidak dilindungi kata sandi. Bundel orientasi tipikal dari bank dikirimkan sebagai pasangan .crt dan .key, terkadang dengan frasa sandi pada kunci.

Langkah 4: Simpan

Pilih Tambah untuk menyimpan sertifikat klien. Sekarang muncul di daftar Anda, terikat pada partner-api.acmebank.com. Sejak saat ini Anda tidak perlu menyentuhnya lagi per permintaan.

Langkah 5: Kirim permintaan terautentikasi

Buat permintaan ke host dan kirimkan:

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

Apidog mencocokkan host, melampirkan sertifikat klien Anda selama jabat tangan TLS, dan menyelesaikan autentikasi mutual TLS sebelum permintaan dikirim. Jika mitra juga memerlukan OAuth, token pembawa tersebut disertakan dalam permintaan seperti biasa. Sertifikat membuktikan mesin; token membuktikan pemanggil. Respons yang berhasil mungkin terlihat seperti ini:

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

Tidak ada langkah manual per permintaan yang membuat itu terjadi. Pencocokan host-lah yang melakukannya.

Menambahkan sertifikat CA untuk root internal atau yang ditandatangani sendiri

Sertifikat klien adalah setengah cerita. Setengah lainnya muncul ketika sertifikat server ditandatangani oleh otoritas yang tidak dipercaya oleh mesin Anda, umum dengan layanan internal dan lingkungan staging yang menggunakan root CA privat.

Ketika itu terjadi, permintaan gagal dengan pesan seperti SSL Error: Self signed certificate bahkan sebelum mTLS mendapatkan kesempatan. Solusinya adalah menyerahkan CA kepada Apidog agar ia mempercayai root tersebut.

Di tab Sertifikat yang sama, aktifkan tombol di samping Sertifikat CA, lalu pilih file PEM Anda. Sertifikat CA menggunakan format PEM, dan satu file PEM dapat menampung beberapa sertifikat CA, sehingga Anda dapat menggabungkan seluruh rantai root internal dan perantara menjadi satu file:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----

Setelah CA dipercaya, Apidog berhenti menolak endpoint yang ditandatangani olehnya. Pasangkan CA yang dipercaya dengan sertifikat klien dan Anda dapat menguji layanan mTLS internal yang menggunakan root privat secara end-to-end: CA memungkinkan Anda mempercayai server mereka, dan sertifikat klien memungkinkan mereka mempercayai Anda.

Tips lanjutan dan variasi umum

Beberapa hal dapat menghemat waktu setelah Anda melewati pengaturan dasar.

Cakupan subdomain dengan satu sertifikat. Jika mitra mengeluarkan sertifikat dengan cakupan wildcard, atur host ke *.acmebank.com sekali saja daripada mendaftarkan partner-api, sandbox-api, dan lainnya secara terpisah. Satu ikatan, setiap subdomain.
Port non-standar. Gateway mTLS internal menyukai port seperti 8443 atau 9443. Defaultnya adalah 443, jadi tentukan port kustom kapan pun endpoint mendengarkan di tempat lain, atau host tidak akan cocok dan tidak ada sertifikat yang terkirim.
Sertifikat tidak dapat diedit setelah ditambahkan. Tidak ada tindakan edit. Untuk merotasi sertifikat yang diperbarui atau memperbaiki kesalahan ketik di host, hapus yang sudah ada dengan ikon hapus dan tambahkan lagi. Masukkan ini ke dalam runbook rotasi sertifikat Anda agar tidak ada yang mencari tombol edit yang tidak ada.
Satu sertifikat per domain. Jangan daftarkan dua sertifikat klien untuk domain yang sama. Setiap ikatan bersifat spesifik domain, dan duplikat akan menimbulkan ambiguitas tentang mana yang harus disajikan Apidog. Pertahankan satu per host.
Pisahkan sertifikat dan Otorisasi di pikiran Anda. Ini adalah sumber kebingungan terbesar. mTLS berada di tab Sertifikat. Kunci API, token pembawa, OAuth, dan autentikasi Dasar berada di tab Otorisasi dari permintaan atau folder, dan permintaan mewarisi otorisasi dari folder induknya. Otorisasi berlaku pada tiga tingkatan: permintaan individual, semua permintaan dalam folder, dan semua permintaan dalam koleksi. Jika mitra memerlukan sertifikat klien dan OAuth, Anda mengatur sertifikat di Sertifikat dan token di Otorisasi. Keduanya tidak tumpang tindih. Untuk melihat lebih dalam tentang pengaturan autentikasi berbasis token, panduan autentikasi gateway API mencakup sisi permintaan, dan jika Anda berurusan dengan tumpukan Windows yang banyak, mengonfigurasi autentikasi Kerberos di Apidog adalah panduan terkait yang layak di bookmark.
Hanya HTTPS, selalu. Apidog tidak akan melampirkan sertifikat klien ke permintaan HTTP biasa. Jika target pengujian Anda adalah http://, sertifikat tidak akan pernah dikirim dan logika jabat tangan tidak akan pernah berjalan. Endpoint harus HTTPS agar semua ini berlaku.

Otomatiskan alur kerja dengan Apidog CLI

Setelah permintaan mTLS Anda berhasil secara manual, masukkan ke dalam skenario pengujian yang disimpan dan jalankan secara headless dengan Apidog CLI. Instal dan autentikasi:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Kemudian jalankan skenario yang disimpan terhadap suatu lingkungan:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Perintah apidog run mendukung konfigurasi sertifikat klien secara langsung, sehingga mTLS tetap berfungsi saat berpindah dari GUI ke pipeline. Untuk sertifikat tunggal, lewatkan --ssl-client-cert (sertifikat PEM), --ssl-client-key (kunci privat), dan --ssl-client-passphrase jika kuncinya memiliki satu. Arahkan --ssl-extra-ca-certs ke CA tepercaya tambahan, atau gunakan --ssl-client-cert-list dengan file konfigurasi saat Anda mencocokkan sertifikat dengan host berdasarkan pola URL. Reporter diatur dengan -r (coba -r html,cli). Sambungkan perintah itu ke dalam sebuah job dan API Anda yang dilindungi sertifikat akan diuji pada setiap push. Panduan Apidog CLI di CI/CD mencakup cara menjalankannya di dalam pipeline.

Pertanyaan yang sering diajukan

Apakah saya memerlukan sertifikat klien dan sertifikat CA, atau hanya salah satunya?

Tergantung pada endpoint. Sertifikat klien membuktikan identitas Anda, jadi Anda membutuhkannya setiap kali server meminta mutual TLS. Sertifikat CA hanya diperlukan ketika sertifikat server itu sendiri ditandatangani oleh otoritas yang belum dipercaya oleh mesin Anda, seperti root CA internal. API mitra publik pada CA publik yang tepercaya hanya memerlukan sertifikat klien; layanan mTLS internal pada root privat biasanya memerlukan keduanya.

Mengapa Apidog tidak mengirim sertifikat klien saya?

Hampir selalu karena ketidakcocokan host atau target HTTP biasa. Periksa apakah kolom Host berisi domain yang tepat tanpa awalan https://, bahwa port cocok (default 443, jadi atur port kustom jika endpoint mendengarkan di tempat lain), dan bahwa URL permintaan adalah HTTPS. Apidog tidak pernah melampirkan sertifikat ke permintaan HTTP.

Di mana kunci API dan token pembawa ditempatkan jika bukan di Sertifikat?

Di tab Otorisasi permintaan atau folder, yang terpisah dari pengaturan sertifikat. Sertifikat menangani identitas lapisan TLS; Otorisasi menangani Kunci API, Token Pembawa, OAuth, dan autentikasi Dasar pada lapisan permintaan. Anda dapat menemukan rincian lengkap jenis autentikasi di panduan skema keamanan, dan Anda dapat mengatur autentikasi sekali pada tingkat folder atau koleksi sehingga setiap permintaan mewarisi itu.

Bisakah satu sertifikat mencakup beberapa subdomain?

Ya. Bidang host mendukung pencocokan pola. Masukkan *.example.com dan sertifikat klien yang sama berlaku untuk setiap subdomain dari example.com. Itu adalah cara yang bersih untuk menggunakan kembali sertifikat cakupan wildcard yang dikeluarkan mitra untuk beberapa subdomain API mereka.

Bagaimana cara memperbarui sertifikat setelah ditambahkan?

Sertifikat tidak dapat diedit di tempat. Hapus yang sudah ada dengan ikon hapus, lalu tambahkan versi yang diperbaiki atau diperbarui. Ingatlah itu untuk rotasi sertifikat, dan saat Anda mengatur persiapan pengujian, pengaturan parameter global di Apidog cocok untuk menjaga nilai lingkungan tetap rapi di seluruh permintaan.

Rangkuman

Menguji API yang dilindungi mTLS bermuara pada tiga langkah di Apidog: mengikat sertifikat klien ke host yang tepat, melampirkan sertifikat CA jika server menggunakan root privat, dan membiarkan pencocokan host menandatangani setiap permintaan HTTPS secara otomatis. Pertahankan sertifikat dan Otorisasi pada jalur terpisah dan jabat tangan tidak lagi menjadi misteri.

Unduh Apidog untuk mengikuti, tambahkan sertifikat mitra Anda, dan kirim permintaan terautentikasi pertama itu. Coba gratis, tidak perlu kartu kredit.