DEV Community

Cover image for วิธีทดสอบ API ที่ต้องใช้ Client Certificates (mTLS) ใน Apidog
Thanawat Wongchai
Thanawat Wongchai

Posted on • Originally published at apidog.com

วิธีทดสอบ API ที่ต้องใช้ Client Certificates (mTLS) ใน Apidog

คุณเรียกใช้ Partner API ส่งคำขอที่จัดรูปแบบถูกต้องและมีโทเค็นแล้ว แต่ยังได้รับข้อผิดพลาด TLS authentication เพราะปลายทางไม่ได้ต้องการแค่ API key หรือ bearer token แต่ต้องการให้ไคลเอนต์พิสูจน์ตัวตนด้วยใบรับรองก่อนส่ง HTTP request ออกจากเครื่อง นี่คือ Mutual TLS (mTLS) และบทความนี้จะแสดงวิธีตั้งค่าใน Apidog เพื่อทดสอบ API ที่ต้องใช้ใบรับรองไคลเอนต์ได้ทันที

ลองใช้ Apidog วันนี้

คู่มือนี้ครอบคลุมการเพิ่ม client certificate และ private key สำหรับโฮสต์เฉพาะ การเพิ่ม CA certificate สำหรับ root CA ภายในหรือ self-signed certificate และการรัน mTLS test ใน CLI/CI หากยังไม่คุ้นกับ certificate error ให้อ่านเรื่อง การตรวจสอบใบรับรอง SSL ควบคู่กันไปได้ สำหรับรายละเอียดโปรโตคอล TLS ดูได้จากเอกสารอ้างอิง MDN TLS

Mutual TLS คืออะไร และทำไม API บางตัวจึงต้องการมัน

ใน HTTPS ปกติ เซิร์ฟเวอร์ส่งใบรับรองมาให้ไคลเอนต์ตรวจสอบ จากนั้นจึงสร้างการเชื่อมต่อที่เข้ารหัสได้ เซิร์ฟเวอร์ยังไม่รู้ตัวตนของไคลเอนต์ในระดับ TLS จึงมักพึ่ง API key, bearer token หรือ OAuth ใน HTTP request

mTLS เพิ่มการยืนยันตัวตนอีกทิศทางหนึ่ง:

  1. เซิร์ฟเวอร์ส่ง server certificate ให้ไคลเอนต์
  2. ไคลเอนต์ตรวจสอบ server certificate
  3. เซิร์ฟเวอร์ร้องขอ client certificate
  4. ไคลเอนต์ส่ง client certificate และพิสูจน์ว่าถือ private key ที่สอดคล้องกัน
  5. เซิร์ฟเวอร์ตรวจสอบว่า certificate นั้นออกโดย CA ที่เชื่อถือได้

หาก client certificate ไม่ถูกต้องหรือไม่มี certificate ที่เซิร์ฟเวอร์เชื่อถือ TLS handshake จะล้มเหลวก่อนส่ง HTTP header หรือ request body

mTLS พบได้บ่อยในกรณีต่อไปนี้:

  • การธนาคารและการชำระเงิน — Open Banking และ payment processor มักใช้ client certificate ร่วมกับ OAuth ดูแนวทางรูปแบบข้อมูลรับรองสำหรับปลายทางการเงินได้จากเอกสาร Stripe
  • ระบบภายในและ service-to-service — สถาปัตยกรรม Zero Trust ใช้ certificate เพื่อยืนยันตัวตนของ service แทนการเชื่อถือเพียง network boundary
  • B2B Partner API — พันธมิตรออก client certificate ให้ระหว่าง onboarding เพื่อจำกัดการเข้าถึงเฉพาะระบบที่ลงทะเบียนไว้

หาก API ใช้ OAuth ร่วมด้วย ทั้งสองกลไกทำงานคนละชั้น:

  • Client certificate: ยืนยันตัวตนระดับ TLS/เครือข่าย
  • Bearer token หรือ OAuth token: ยืนยันตัวตนและสิทธิ์ระดับแอปพลิเคชัน

RFC 8705 อธิบายการผูก OAuth token กับ mTLS client certificate เพิ่มเติม ใน Apidog ให้จำไว้ว่า:

  • ตั้งค่า mTLS ที่ Certificates
  • ตั้งค่า API Key, Bearer Token, OAuth และ Basic Auth ที่ Authorization

ดูรายละเอียดการตั้งค่า authorization ได้ที่Security Schemes

Apidog กำหนดขอบเขตใบรับรองตามโฮสต์อย่างไร

Apidog จัดการทั้ง CA certificate และ client certificate ในการตั้งค่าแบบ global โดยผูก certificate กับ host เมื่อ URL ของ request ตรงกับ host ที่กำหนดไว้ Apidog จะแนบ client certificate ระหว่าง TLS handshake โดยอัตโนมัติ

ใบรับรองแต่ละประเภทมีหน้าที่ต่างกัน:

ประเภท ใช้ทำอะไร
Client certificate พิสูจน์ตัวตนของไคลเอนต์ต่อเซิร์ฟเวอร์สำหรับ mTLS
CA certificate เพิ่ม CA ที่ Apidog ควรเชื่อถือ เช่น private root CA หรือ self-signed CA

ตัวอย่าง error ที่แก้ด้วย CA certificate:

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

จุดสำคัญคือการจับคู่ host หาก host หรือ port ไม่ตรงกับ request Apidog จะไม่เลือก certificate นั้นมาใช้

ตั้งค่าใบรับรองไคลเอนต์สำหรับ mTLS API

สมมติว่า Partner API คือ:

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

และ API ต้องใช้ client certificate เพื่อเรียก endpoint:

GET /v1/settlements
Enter fullscreen mode Exit fullscreen mode

ขั้นตอนที่ 1: เปิดการตั้งค่า Certificates

  1. เปิด Apidog
  2. คลิกไอคอนการตั้งค่ามุมขวาบน
  3. ไปที่แท็บ Certificates

หน้านี้เป็นจุดตั้งค่า certificate แบบ global ไม่จำเป็นต้องแนบไฟล์ใหม่ในทุก request

ขั้นตอนที่ 2: เพิ่ม Client Certificate

ใต้หัวข้อ Client Certificates ให้เลือก Add Certificate

กรอกช่อง Host ด้วยโดเมนเท่านั้น:

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

อย่าใส่ protocol:

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

หาก certificate เดียวครอบคลุมหลาย subdomain ให้ใช้ wildcard ได้ เช่น:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

ตัวอย่างนี้จะใช้ certificate เดียวกันกับ:

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

ขั้นตอนที่ 3: ตั้งค่า Port

ค่าเริ่มต้นคือ HTTPS port 443 จึงไม่จำเป็นต้องกรอกหาก API ใช้ port มาตรฐาน

หากปลายทางใช้ port อื่น ให้กำหนด port ให้ตรงกับ URL เช่น:

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

จากนั้น request ต้องเรียกด้วย port เดียวกัน:

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

ขั้นตอนที่ 4: เลือกไฟล์ Certificate และ Key

Apidog รองรับ client certificate สองรูปแบบหลัก:

  • CRT + Key — certificate และ private key แยกคนละไฟล์
  • PFX — ไฟล์เดียวที่รวม certificate และ private key

เลือกไฟล์ตามที่ Partner API ส่งให้ ตัวอย่างไฟล์ที่พบบ่อย:

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

หรือ:

client.pfx
Enter fullscreen mode Exit fullscreen mode

หาก private key หรือ PFX มีรหัสผ่าน ให้กรอกในช่อง passphrase หากไม่มีรหัสผ่านให้ปล่อยว่างได้

ขั้นตอนที่ 5: บันทึกและส่ง Request

คลิก Add เพื่อบันทึก certificate binding

จากนั้นสร้าง request ตามปกติ:

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

เมื่อส่ง request แล้ว Apidog จะทำงานตามลำดับนี้:

  1. จับคู่ host กับ client certificate ที่ตั้งค่าไว้
  2. ส่ง client certificate ระหว่าง TLS handshake
  3. ทำ mTLS authentication กับเซิร์ฟเวอร์
  4. ส่ง HTTP request พร้อม bearer token ตามปกติ

ตัวอย่าง response:

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

เพิ่ม CA Certificate สำหรับ Root ภายในหรือ Self-Signed Certificate

Client certificate ช่วยให้เซิร์ฟเวอร์เชื่อถือไคลเอนต์ แต่ไคลเอนต์ก็ต้องเชื่อถือ certificate ของเซิร์ฟเวอร์ด้วย

ในระบบภายในหรือ test environment เซิร์ฟเวอร์อาจใช้ certificate ที่ออกโดย private CA หรือ self-signed CA ซึ่งไม่ได้อยู่ใน trusted CA store ปกติ ทำให้ request ล้มเหลวตั้งแต่ก่อน mTLS handshake

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

วิธีแก้คือเพิ่ม CA certificate ใน Apidog:

  1. เปิด Settings
  2. ไปที่ Certificates
  3. เปิดใช้งาน CA Certificates
  4. เลือกไฟล์ CA ในรูปแบบ PEM

ไฟล์ PEM หนึ่งไฟล์สามารถรวม root และ intermediate CA ได้หลายรายการ เช่น:

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

หลังเพิ่ม CA แล้ว:

  • Apidog เชื่อถือ server certificate ที่ออกโดย CA นี้
  • Server เชื่อถือ client certificate ของคุณผ่าน mTLS
  • คุณสามารถทดสอบ internal mTLS service ได้ครบทั้งสองทิศทาง

เคล็ดลับและข้อควรตรวจสอบ

ใช้ wildcard สำหรับหลาย subdomain

หาก Partner ออก certificate เดียวให้หลาย API subdomain ให้ใช้:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

แทนการสร้าง binding แยกสำหรับทุก host

กำหนด custom port ให้ตรง

หาก endpoint ใช้ 8443 หรือ 9443 อย่าปล่อยให้ Apidog ใช้ค่า default 443

ตัวอย่าง:

GET https://internal-api.example.com:9443/health
Enter fullscreen mode Exit fullscreen mode

ต้องตั้งค่า host และ port เป็น:

Host: internal-api.example.com
Port: 9443
Enter fullscreen mode Exit fullscreen mode

ใบรับรองแก้ไขหลังเพิ่มไม่ได้

หาก certificate หมดอายุ ถูกต่ออายุ หรือพิมพ์ host ผิด ให้:

  1. ลบ certificate เดิมด้วยไอคอนลบ
  2. เพิ่ม certificate ใหม่

ใส่ขั้นตอนนี้ไว้ใน certificate rotation runbook ของทีม

ใช้ certificate เดียวต่อ host

หลีกเลี่ยงการเพิ่ม client certificate หลายรายการสำหรับ host เดียวกัน เพราะจะทำให้เกิดความกำกวมว่า certificate ใดควรถูกส่งใน TLS handshake

แยก Certificates ออกจาก Authorization

ใช้ตารางนี้เป็น checklist ก่อน debug:

ปัญหา จุดที่ต้องตั้งค่า
mTLS client certificate Certificates
Private CA / self-signed CA Certificates
API Key Authorization
Bearer Token Authorization
OAuth Authorization
Basic Auth Authorization

Authorization สามารถกำหนดได้ที่ระดับ request, folder หรือ collection เพื่อให้ request สืบทอดการตั้งค่าได้

สำหรับการตั้งค่า token authentication เพิ่มเติม ดูคู่มือการตรวจสอบสิทธิ์ API gateway และสำหรับระบบ Windows ดูการกำหนดค่า Kerberos authentication ใน Apidog

mTLS ใช้ได้กับ HTTPS เท่านั้น

Apidog จะไม่แนบ client certificate กับ URL ที่เป็น HTTP ปกติ:

http://example.com
Enter fullscreen mode Exit fullscreen mode

ต้องใช้ HTTPS:

https://example.com
Enter fullscreen mode Exit fullscreen mode

ทำให้ mTLS Test เป็นอัตโนมัติด้วย Apidog CLI

หลังจากทดสอบ request ผ่านใน UI แล้ว คุณสามารถนำ scenario เดิมไปรันใน CI/CD ด้วย Apidog CLI

ติดตั้ง CLI และล็อกอิน:

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

รัน scenario กับ environment ที่ต้องการ:

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

สำหรับ mTLS ให้กำหนด certificate โดยตรงผ่าน CLI options:

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

ตัวเลือกที่เกี่ยวข้อง:

Option ใช้สำหรับ
--ssl-client-cert ไฟล์ client certificate แบบ PEM
--ssl-client-key private key ของ client certificate
--ssl-client-passphrase passphrase ของ private key หากมี
--ssl-extra-ca-certs ไฟล์ CA เพิ่มเติมที่ต้องเชื่อถือ
--ssl-client-cert-list ไฟล์ config สำหรับจับคู่ certificate กับ host ตาม URL pattern
-r html,cli สร้างรายงาน HTML และแสดงผลใน CLI

เก็บ certificate และ private key เป็น secret ของ CI provider ไม่ควร commit ลง repository จากนั้นเชื่อมคำสั่ง apidog run เข้ากับ pipeline เพื่อรัน mTLS regression test ทุกครั้งที่มีการ push โค้ด

ดูตัวอย่างการใช้งานใน pipeline เพิ่มเติมได้จากคู่มือ Apidog CLI ใน CI/CD

คำถามที่พบบ่อย

ต้องใช้ทั้ง Client Certificate และ CA Certificate หรือไม่?

ขึ้นอยู่กับปลายทาง:

  • ใช้ client certificate เมื่อเซิร์ฟเวอร์บังคับ mTLS
  • ใช้ CA certificate เมื่อ server certificate ออกโดย CA ที่เครื่องยังไม่เชื่อถือ
  • API สาธารณะที่ใช้ public CA มักต้องการเพียง client certificate
  • Internal mTLS service ที่ใช้ private root CA มักต้องใช้ทั้งสองอย่าง

ทำไม Apidog ไม่ส่ง Client Certificate?

ตรวจสอบตามลำดับนี้:

  1. ช่อง Host เป็นโดเมนที่ถูกต้องและไม่มี https://
  2. request ใช้ HTTPS
  3. port ใน certificate binding ตรงกับ port ของ URL
  4. ไม่มี certificate ซ้ำสำหรับ host เดียวกัน
  5. certificate และ private key เป็นคู่ที่ตรงกัน

API Key และ Bearer Token ต้องตั้งค่าที่ไหน?

ตั้งค่าที่แท็บ Authorization ของ request, folder หรือ collection ไม่ได้ตั้งใน Certificates

อ่านรายละเอียดได้จากคู่มือ Security Schemes

Certificate เดียวครอบคลุมหลาย Subdomain ได้หรือไม่?

ได้ ใช้ wildcard host pattern:

*.example.com
Enter fullscreen mode Exit fullscreen mode

certificate เดียวกันจะถูกใช้กับทุก subdomain ภายใต้ example.com

อัปเดต Certificate ที่เพิ่มไว้แล้วอย่างไร?

Apidog ไม่รองรับการแก้ไข certificate ที่เพิ่มแล้ว ให้ลบรายการเดิมและเพิ่ม certificate ที่ต่ออายุหรือแก้ไขแล้วใหม่

หากต้องการจัดการค่าระหว่าง environment ให้เป็นระบบมากขึ้น อ่านการตั้งค่าพารามิเตอร์ Global ใน Apidog

สรุป

การทดสอบ API ที่ใช้ mTLS ใน Apidog มีสามขั้นตอนหลัก:

  1. ผูก client certificate กับ host และ port ที่ถูกต้อง
  2. เพิ่ม CA certificate หากเซิร์ฟเวอร์ใช้ private หรือ self-signed root CA
  3. ตั้งค่า OAuth, API key หรือ bearer token แยกใน Authorization หาก API ต้องการ

เมื่อ host ตรงกัน Apidog จะส่ง client certificate ใน TLS handshake โดยอัตโนมัติ ทำให้คุณโฟกัสกับการทดสอบ request และ response ได้แทนการจัดการ certificate ในทุก request

ดาวน์โหลด Apidog เพื่อตั้งค่า certificate ของ Partner API และทดสอบ mTLS request แรกของคุณ

Top comments (0)