DEV Community

Cover image for Cara Menguji API dengan Sertifikat Klien (mTLS) di Apidog
Walse
Walse

Posted on • Originally published at apidog.com

Cara Menguji API dengan Sertifikat Klien (mTLS) di Apidog

Anda mengakses API mitra, mengirim permintaan yang valid dengan token yang benar, tetapi koneksi tetap gagal pada tahap TLS handshake. Penyebabnya bisa jadi endpoint tersebut meminta sertifikat klien untuk membuktikan identitas aplikasi Anda sebelum permintaan HTTP dikirim. Mekanisme ini disebut mutual TLS (mTLS).

Coba Apidog sekarang

Panduan ini menunjukkan cara mengonfigurasi sertifikat klien dan sertifikat CA di Apidog untuk menguji API yang dilindungi mTLS. Anda akan:

  1. Mengikat sertifikat klien ke host API.
  2. Menambahkan CA privat atau self-signed agar server dapat dipercaya.
  3. Mengirim permintaan HTTPS yang otomatis menggunakan sertifikat tersebut.
  4. Menjalankan pengujian mTLS dari CLI dan pipeline CI/CD.

Jika Anda baru menangani error sertifikat, baca juga panduan verifikasi sertifikat SSL. Untuk konsep protokolnya, lihat referensi TLS dari MDN.

Apa itu mutual TLS dan kapan digunakan?

Pada HTTPS biasa, validasi identitas berjalan satu arah:

  1. Server mengirim sertifikatnya.
  2. Klien memverifikasi sertifikat server.
  3. Koneksi terenkripsi dibuat.
  4. Klien mengirim token, API key, atau kredensial lain di dalam request.

Pada mutual TLS, server juga meminta sertifikat dari klien. Jika sertifikat klien tidak valid atau tidak dipercaya server, TLS handshake gagal sebelum header dan body HTTP dikirim.

mTLS umum digunakan pada:

  • Perbankan dan pembayaran — API open banking atau pemrosesan kartu sering menggabungkan sertifikat klien dengan OAuth. Lihat dokumentasi Stripe untuk contoh model kredensial berlapis pada endpoint sensitif.
  • Komunikasi service-to-service — arsitektur zero-trust dapat menggunakan sertifikat untuk memverifikasi identitas setiap layanan.
  • API mitra B2B — mitra dapat menerbitkan sertifikat klien saat onboarding agar hanya sistem terdaftar yang dapat mengakses API.

Jika API memakai OAuth sekaligus mTLS, keduanya tetap terpisah:

  • Sertifikat klien: membuktikan identitas pada lapisan TLS.
  • Token OAuth atau Bearer token: membuktikan identitas pemanggil pada lapisan aplikasi.

RFC 8705 menjelaskan pengikatan token OAuth dengan sertifikat klien melalui mTLS.

Di Apidog:

  • Tab Sertifikat digunakan untuk mTLS.
  • Tab Otorisasi digunakan untuk API key, Bearer token, OAuth, dan Basic Auth.

Cara Apidog mencocokkan sertifikat berdasarkan host

Apidog menyimpan konfigurasi sertifikat secara global dan menerapkannya berdasarkan host tujuan request. Anda tidak perlu menambahkan sertifikat secara manual pada setiap request.

Saat request HTTPS dikirim:

  1. Apidog membaca hostname dari URL.
  2. Apidog mencari konfigurasi sertifikat klien yang cocok.
  3. Jika cocok, Apidog melampirkan sertifikat saat TLS handshake.
  4. Request HTTP baru dikirim setelah handshake berhasil.

Ada dua jenis sertifikat yang perlu dibedakan:

  • Sertifikat klien: dikirim ke server untuk membuktikan identitas Anda pada mTLS.
  • Sertifikat CA: digunakan Apidog untuk mempercayai sertifikat server dari CA internal atau self-signed.

Misalnya, error berikut menunjukkan masalah kepercayaan terhadap sertifikat server:

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

Solusinya bukan menambahkan Bearer token, melainkan menambahkan sertifikat CA yang tepat.

Menyiapkan sertifikat klien untuk API mTLS

Contoh berikut menggunakan API mitra:

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

Mitra memberikan:

  • Sertifikat klien, misalnya client.crt
  • Kunci privat, misalnya client.key
  • Atau satu bundle client.pfx
  • Passphrase, jika kunci privat dilindungi kata sandi

Target request:

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

1. Buka pengaturan Sertifikat

Di Apidog:

  1. Klik ikon Settings di kanan atas.
  2. Buka tab Sertifikat.
  3. Cari bagian Sertifikat Klien.

Konfigurasi di halaman ini tidak hanya berlaku untuk satu request. Apidog akan menggunakannya untuk semua request yang host-nya cocok.

2. Tambahkan sertifikat klien

Pada bagian Sertifikat Klien, klik Tambah Sertifikat.

Isi field Host dengan domain tanpa protokol:

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

Jangan memasukkan nilai seperti ini:

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

Host harus berupa nama domain mentah.

Jika sertifikat yang sama berlaku untuk banyak subdomain, gunakan wildcard:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Konfigurasi ini dapat mencakup host seperti:

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

3. Atur port jika endpoint tidak menggunakan 443

Secara default, HTTPS menggunakan port 443. Biarkan field port kosong jika endpoint Anda menggunakan port standar.

Jika API mTLS berjalan pada port lain, tentukan port tersebut, misalnya:

8443
Enter fullscreen mode Exit fullscreen mode

Ini penting karena host dan port harus cocok dengan request yang dikirim. Jika konfigurasi tidak cocok, Apidog tidak akan mengirim sertifikat klien.

4. Pilih format sertifikat

Apidog mendukung dua format umum.

Opsi A: CRT + Key

Pilih file sertifikat dan kunci privat secara terpisah:

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

Opsi B: PFX

Pilih satu file bundle:

client.pfx
Enter fullscreen mode Exit fullscreen mode

Jika file atau kunci privat memiliki passphrase, isi field frasa sandi. Jika tidak, biarkan kosong.

5. Simpan konfigurasi

Klik Tambah untuk menyimpan.

Setelah disimpan, sertifikat akan terikat ke host:

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

Mulai sekarang, Apidog akan otomatis menggunakannya untuk request HTTPS ke host tersebut.

6. Kirim request yang membutuhkan mTLS

Buat request seperti biasa:

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

Pada proses pengiriman request, Apidog akan:

  1. Mencocokkan host partner-api.acmebank.com.
  2. Mengirim sertifikat klien saat TLS handshake.
  3. Memvalidasi koneksi mTLS.
  4. Mengirim header Authorization setelah koneksi TLS berhasil dibuat.

Contoh respons:

{
  "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

Menambahkan sertifikat CA untuk root internal atau self-signed

Sertifikat klien hanya menyelesaikan sisi autentikasi klien. Anda juga perlu menambahkan CA jika sertifikat server ditandatangani oleh CA internal atau self-signed.

Gejalanya biasanya berupa error:

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

Untuk memperbaikinya:

  1. Buka Settings > Sertifikat.
  2. Aktifkan Sertifikat CA.
  3. Pilih file CA berformat PEM.

File PEM dapat memuat satu atau beberapa sertifikat dalam satu chain:

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

Anda dapat menggabungkan root CA dan intermediate CA dalam satu file PEM jika diperlukan.

Dengan konfigurasi ini:

  • Sertifikat CA membuat Apidog mempercayai server.
  • Sertifikat klien membuat server mempercayai Anda.

Keduanya diperlukan untuk banyak layanan internal yang menggunakan mTLS dan PKI privat.

Troubleshooting mTLS di Apidog

Gunakan checklist berikut ketika sertifikat tidak terkirim atau handshake gagal.

Pastikan URL menggunakan HTTPS

Sertifikat klien hanya dikirim untuk request HTTPS.

Benar:

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

Salah:

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

Pada URL http://, tidak ada TLS handshake dan sertifikat klien tidak akan digunakan.

Pastikan host tidak menyertakan protokol

Gunakan:

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

Jangan gunakan:

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

Pastikan port cocok

Jika endpoint menggunakan:

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

Tambahkan port 8443 pada konfigurasi sertifikat. Konfigurasi dengan default 443 tidak akan cocok.

Gunakan satu sertifikat untuk satu domain

Jangan mendaftarkan beberapa sertifikat klien untuk domain yang sama. Konfigurasi duplikat dapat membuat pemilihan sertifikat menjadi ambigu.

Jika Anda perlu merotasi sertifikat:

  1. Hapus sertifikat lama.
  2. Tambahkan sertifikat baru.
  3. Uji request HTTPS kembali.

Sertifikat yang telah ditambahkan tidak dapat diedit langsung.

Pisahkan mTLS dan otorisasi request

mTLS bukan pengganti OAuth atau API key.

Gunakan tab Sertifikat untuk:

  • Sertifikat klien
  • Kunci privat
  • Sertifikat CA

Gunakan tab Otorisasi untuk:

  • API Key
  • Bearer Token
  • OAuth 2.0
  • Basic Auth

Otorisasi dapat diterapkan pada level request, folder, atau collection. Untuk detailnya, baca panduan skema keamanan.

Untuk pola autentikasi berbasis gateway, lihat panduan autentikasi gateway API. Jika Anda bekerja dengan lingkungan Windows dan Kerberos, lihat juga konfigurasi autentikasi Kerberos di Apidog.

Menjalankan pengujian mTLS dengan Apidog CLI

Setelah request mTLS berhasil di GUI, simpan request atau skenario pengujian lalu jalankan secara headless menggunakan Apidog CLI.

Instal CLI dan autentikasi:

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

Jalankan skenario pada environment tertentu:

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

Untuk menjalankan mTLS dari CLI, gunakan parameter sertifikat yang sesuai:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  --ssl-client-cert ./client.crt \
  --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

Parameter yang relevan:

Parameter Fungsi
--ssl-client-cert Path ke sertifikat klien PEM
--ssl-client-key Path ke kunci privat
--ssl-client-passphrase Passphrase kunci privat, jika ada
--ssl-extra-ca-certs Path ke CA tambahan yang dipercaya
--ssl-client-cert-list Konfigurasi beberapa sertifikat berdasarkan pola URL
-r html,cli Menghasilkan laporan HTML dan output CLI

Tambahkan perintah tersebut ke job CI/CD agar API mTLS diuji pada setiap push atau deployment. Lihat panduan Apidog CLI di CI/CD untuk integrasi pipeline.

Pertanyaan yang sering diajukan

Apakah saya selalu membutuhkan sertifikat klien dan sertifikat CA?

Tidak selalu.

  • Anda membutuhkan sertifikat klien jika server meminta mTLS.
  • Anda membutuhkan sertifikat CA jika sertifikat server ditandatangani oleh CA yang belum dipercaya, misalnya CA internal atau self-signed.

API publik dengan sertifikat dari CA publik biasanya hanya membutuhkan sertifikat klien untuk mTLS. Layanan internal dengan root CA privat sering membutuhkan keduanya.

Mengapa Apidog tidak mengirim sertifikat klien saya?

Periksa tiga hal:

  1. Host di konfigurasi sertifikat harus sama dengan host request.
  2. Jangan memasukkan https:// pada field host.
  3. Pastikan URL request menggunakan HTTPS.
  4. Jika endpoint memakai port non-standar, pastikan port konfigurasi cocok.

Apakah satu sertifikat dapat digunakan untuk beberapa subdomain?

Ya, jika sertifikat dan kebijakan mitra mendukungnya. Gunakan pola wildcard:

*.example.com
Enter fullscreen mode Exit fullscreen mode

Sertifikat tersebut akan diterapkan ke subdomain seperti:

api.example.com
sandbox.example.com
partner.example.com
Enter fullscreen mode Exit fullscreen mode

Bagaimana cara memperbarui sertifikat?

Hapus sertifikat lama, lalu tambahkan sertifikat baru. Tidak ada opsi edit langsung untuk konfigurasi sertifikat yang sudah tersimpan.

Untuk menjaga nilai environment tetap konsisten di banyak request, gunakan parameter global di Apidog.

Rangkuman

Untuk menguji API yang dilindungi mTLS di Apidog:

  1. Tambahkan sertifikat klien dan ikat ke host yang benar.
  2. Tambahkan sertifikat CA jika server memakai CA privat atau self-signed.
  3. Pastikan request menggunakan HTTPS dan port yang sesuai.
  4. Konfigurasikan OAuth, API key, atau Bearer token secara terpisah di tab Otorisasi.
  5. Jalankan skenario yang sama melalui Apidog CLI untuk CI/CD.

Unduh Apidog, tambahkan sertifikat mitra Anda, lalu uji request mTLS pertama Anda.

Top comments (0)