DEV Community

Cover image for Hướng dẫn kiểm thử API mTLS bằng Apidog
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng dẫn kiểm thử API mTLS bằng Apidog

Bạn gọi một API đối tác với payload đúng định dạng và token hợp lệ nhưng vẫn nhận lỗi TLS handshake failure. Nguyên nhân có thể là endpoint yêu cầu client chứng minh danh tính bằng chứng chỉ trước khi bất kỳ yêu cầu HTTP nào được gửi đi. Đây là TLS song phương (mutual TLS hoặc mTLS), và việc cấu hình sai chứng chỉ có thể chặn toàn bộ quá trình tích hợp.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này trình bày cách cấu hình chứng chỉ client và chứng chỉ CA trong Apidog để kiểm thử API bảo vệ bằng mTLS. Bạn sẽ liên kết chứng chỉ client với một host, thêm CA cho chứng chỉ tự ký hoặc root nội bộ, rồi gửi yêu cầu HTTPS đã được Apidog tự động ký. Nếu bạn mới làm việc với chứng chỉ, hãy đọc thêm về xác minh chứng chỉ SSL. Để hiểu giao thức nền tảng, xem tài liệu TLS của MDN.

TLS song phương là gì và tại sao API yêu cầu nó?

Với HTTPS thông thường, việc xác minh diễn ra một chiều:

  1. Máy chủ gửi chứng chỉ của nó.
  2. Client xác minh chứng chỉ đó.
  3. Kết nối mã hóa được thiết lập.
  4. Client gửi token hoặc API key trong yêu cầu để xác thực ở tầng ứng dụng.

Với mTLS, máy chủ cũng yêu cầu client gửi chứng chỉ:

  1. Máy chủ trình bày chứng chỉ TLS.
  2. Client xác minh chứng chỉ máy chủ.
  3. Client trình bày chứng chỉ client.
  4. Máy chủ xác minh chứng chỉ client.
  5. Chỉ khi cả hai bên được tin cậy, yêu cầu HTTP mới được gửi.

Nếu chứng chỉ client không được ký bởi CA mà máy chủ tin cậy, quá trình bắt tay thất bại. Khi đó sẽ không có header, body hay token nào được truyền đi.

mTLS thường xuất hiện trong các trường hợp sau:

  • Ngân hàng và thanh toán: API ngân hàng mở hoặc hệ thống xử lý thẻ thường yêu cầu chứng chỉ client bên cạnh OAuth. Tài liệu Stripe mô tả mô hình thông tin xác thực nhiều lớp cho endpoint tài chính nhạy cảm.
  • Giao tiếp nội bộ giữa các dịch vụ: Môi trường zero-trust yêu cầu dịch vụ xác minh danh tính bằng chứng chỉ thay vì chỉ dựa vào mạng nội bộ.
  • API đối tác B2B: Đối tác có thể cấp chứng chỉ client trong quá trình onboarding để giới hạn quyền truy cập cho các máy hoặc hệ thống đã đăng ký.

Nếu API sử dụng cả OAuth và mTLS, hai cơ chế này không thay thế nhau. RFC 8705 mô tả cách liên kết token OAuth với chứng chỉ client.

Chứng chỉ client xác thực ở tầng TLS/network.

Token, API key, OAuth và Basic Auth xác thực ở tầng HTTP/application.

Trong Apidog:

  • Tab Certificates dùng để cấu hình mTLS.
  • Tab Authorization dùng cho API key, Bearer token, OAuth và Basic Auth.

Bạn có thể cần cấu hình cả hai.

Apidog liên kết chứng chỉ với host như thế nào?

Apidog cấu hình chứng chỉ ở phạm vi toàn cục, không phải trên từng request. Bạn thêm chứng chỉ một lần, liên kết nó với host, và Apidog tự động sử dụng chứng chỉ đó cho mọi yêu cầu HTTPS khớp với host.

Có hai loại chứng chỉ cần phân biệt:

Loại Mục đích
Client Certificate Chứng minh danh tính client với máy chủ trong quy trình mTLS.
CA Certificate Cho phép Apidog tin cậy máy chủ sử dụng CA nội bộ hoặc chứng chỉ tự ký.

Ví dụ:

  • API đối tác yêu cầu mTLS → thêm client certificate.
  • Server staging dùng private root CA → thêm CA certificate.
  • API nội bộ dùng cả mTLS và private CA → cần cả hai.

Việc khớp dựa trên host. Nếu host cấu hình không khớp URL yêu cầu, Apidog sẽ không gửi chứng chỉ client.

Thiết lập chứng chỉ client cho API mTLS

Giả sử đối tác cấp cho bạn:

  • Host: partner-api.acmebank.com
  • Endpoint: GET /v1/settlements
  • Một chứng chỉ client và private key
  • OAuth token để xác thực yêu cầu

Bước 1: Mở phần Certificates

Trong Apidog:

  1. Chọn biểu tượng cài đặt ở góc trên bên phải.
  2. Mở tab Certificates.
  3. Tìm phần Client Certificates.

Các chứng chỉ tại đây sẽ được áp dụng tự động dựa trên host, thay vì gắn vào một request riêng lẻ.

Bước 2: Thêm client certificate

Trong phần Client Certificates, chọn Add Certificate.

Ở trường Host, chỉ nhập tên miền:

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

Không nhập giao thức:

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

Nếu đối tác sử dụng cùng chứng chỉ cho nhiều subdomain, bạn có thể dùng wildcard:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Ví dụ này có thể áp dụng cùng chứng chỉ cho:

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

Cổng mặc định là 443. Chỉ điền cổng nếu endpoint mTLS dùng cổng khác, chẳng hạn:

8443
Enter fullscreen mode Exit fullscreen mode

Bước 3: Chọn định dạng chứng chỉ

Apidog hỗ trợ hai dạng phổ biến.

Cách 1: CRT và private key riêng biệt

Chọn:

  • File chứng chỉ, ví dụ .crt
  • File private key, ví dụ .key

Ví dụ:

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

Cách 2: File PFX

Nếu đối tác cấp một file chứa cả chứng chỉ và private key, chọn file .pfx.

client-certificate.pfx
Enter fullscreen mode Exit fullscreen mode

Nếu private key hoặc PFX có passphrase, nhập passphrase vào trường tương ứng. Nếu không có, để trống.

Bước 4: Lưu chứng chỉ

Chọn Add để lưu.

Sau khi lưu, chứng chỉ được liên kết với:

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

Từ thời điểm này, Apidog sẽ tự động dùng chứng chỉ khi bạn gọi HTTPS đến host đó.

Bước 5: Gửi yêu cầu mTLS

Tạo request:

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

Apidog thực hiện các bước sau:

  1. Khớp host với cấu hình certificate.
  2. Gửi client certificate trong TLS handshake.
  3. Hoàn tất xác thực mTLS.
  4. Gửi Bearer token trong HTTP request.

Ví dụ phản hồi thành công:

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

Chứng chỉ xác thực máy hoặc hệ thống gọi API; token xác thực phiên, ứng dụng hoặc người dùng ở tầng HTTP.

Thêm chứng chỉ CA cho root nội bộ hoặc chứng chỉ tự ký

Client certificate chỉ xử lý việc máy chủ xác minh bạn. Bạn cũng cần xử lý chiều ngược lại: client phải tin cậy chứng chỉ của máy chủ.

Nếu server dùng chứng chỉ được ký bởi CA nội bộ hoặc chứng chỉ tự ký, request có thể thất bại với lỗi:

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

Lỗi này xảy ra trước khi mTLS hoàn tất.

Cách thêm CA certificate

Trong tab Certificates:

  1. Bật CA Certificates.
  2. Chọn file CA ở định dạng PEM.
  3. Lưu cấu hình.

Một file PEM có thể chứa nhiều chứng chỉ, bao gồm root CA và intermediate CA:

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

Sau khi thêm CA:

  • Apidog có thể tin cậy server được ký bởi CA này.
  • Client certificate cho phép server tin cậy bạn.
  • Kết nối mTLS nội bộ có thể hoạt động từ đầu đến cuối.

Mẹo cấu hình mTLS trong Apidog

Dùng wildcard cho nhiều subdomain

Nếu một chứng chỉ áp dụng cho nhiều endpoint của đối tác, dùng:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Thay vì thêm riêng từng host:

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

Kiểm tra cổng không chuẩn

Nếu API dùng cổng như 8443 hoặc 9443, hãy cấu hình đúng cổng trong certificate settings.

Ví dụ URL:

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

Nếu bạn không cấu hình cổng phù hợp, host có thể không khớp và Apidog sẽ không gửi chứng chỉ.

Chứng chỉ không thể chỉnh sửa trực tiếp

Nếu cần thay chứng chỉ đã gia hạn hoặc sửa host:

  1. Xóa chứng chỉ cũ.
  2. Thêm lại chứng chỉ mới.

Đưa bước này vào quy trình xoay vòng chứng chỉ để tránh gián đoạn kiểm thử.

Chỉ giữ một chứng chỉ cho mỗi host

Không nên đăng ký nhiều client certificate cho cùng một tên miền. Điều này tạo ra sự mơ hồ về chứng chỉ cần gửi trong handshake.

Mỗi host nên có một certificate binding rõ ràng.

Tách biệt Certificates và Authorization

Đây là lỗi cấu hình phổ biến nhất:

Cấu hình Vị trí trong Apidog
Client certificate, CA certificate, mTLS Certificates
API key, Bearer token, OAuth, Basic Auth Authorization

Authorization có thể được cấu hình ở:

  • Từng request
  • Folder
  • Collection

Các request có thể kế thừa authorization từ folder hoặc collection cha.

Để tìm hiểu thêm về token-based authentication, xem hướng dẫn xác thực gateway API. Nếu bạn làm việc trong môi trường Windows, xem thêm bài cấu hình xác thực Kerberos trong Apidog.

mTLS chỉ hoạt động với HTTPS

Apidog không gửi client certificate cho URL HTTP thuần túy:

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

URL phải dùng HTTPS:

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

Nếu endpoint bắt đầu bằng http://, TLS handshake sẽ không chạy và chứng chỉ sẽ không được gửi.

Tự động hóa kiểm thử mTLS bằng Apidog CLI

Sau khi request chạy được trong giao diện Apidog, bạn có thể chạy scenario trong CI/CD bằng Apidog CLI.

Cài đặt CLI:

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

Chạy scenario đã lưu với một environment:

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

Apidog CLI hỗ trợ truyền trực tiếp cấu hình chứng chỉ:

  • --ssl-client-cert: đường dẫn đến chứng chỉ PEM
  • --ssl-client-key: đường dẫn đến private key
  • --ssl-client-passphrase: passphrase của private key
  • --ssl-extra-ca-certs: CA bổ sung cần tin cậy
  • --ssl-client-cert-list: file cấu hình ánh xạ chứng chỉ theo mẫu URL

Ví dụ với nhiều reporter:

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

Bạn có thể đưa lệnh này vào pipeline để kiểm thử API mTLS trên mỗi lần push. Xem hướng dẫn chạy Apidog CLI trong CI/CD để tích hợp vào pipeline.

Câu hỏi thường gặp

Tôi cần client certificate, CA certificate hay cả hai?

Tùy vào endpoint:

  • Cần client certificate khi server yêu cầu mTLS.
  • Cần CA certificate khi server dùng CA chưa được máy bạn tin cậy, chẳng hạn private root CA.
  • Cần cả hai khi API nội bộ vừa dùng mTLS vừa sử dụng chứng chỉ server được ký bởi private CA.

API công khai sử dụng CA công khai thường chỉ cần client certificate.

Tại sao Apidog không gửi client certificate?

Kiểm tra các điểm sau:

  1. Host trong cấu hình phải khớp chính xác URL request.
  2. Không thêm https:// vào trường Host.
  3. Cổng phải khớp nếu endpoint không dùng 443.
  4. URL request phải bắt đầu bằng https://.

Ví dụ host đúng:

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

Ví dụ host sai:

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

API key và Bearer token được cấu hình ở đâu?

Cấu hình chúng trong tab Authorization, không phải Certificates.

Xem thêm hướng dẫn về sơ đồ bảo mật để phân biệt các loại xác thực và cách kế thừa Authorization trong collection.

Một chứng chỉ có thể dùng cho nhiều subdomain không?

Có. Dùng wildcard trong trường Host:

*.example.com
Enter fullscreen mode Exit fullscreen mode

Cấu hình này áp dụng chứng chỉ cho mọi subdomain của example.com.

Làm cách nào để cập nhật chứng chỉ?

Chứng chỉ không chỉnh sửa trực tiếp được. Hãy xóa certificate hiện có và thêm lại certificate mới hoặc certificate đã gia hạn.

Khi quản lý nhiều môi trường, bạn cũng có thể dùng tham số toàn cục trong Apidog để giữ URL, token và giá trị môi trường nhất quán giữa các request.

Tổng kết

Để kiểm thử API mTLS trong Apidog:

  1. Liên kết client certificate với đúng host.
  2. Thêm CA certificate nếu server dùng private root hoặc chứng chỉ tự ký.
  3. Gửi request HTTPS để Apidog tự động chọn và đính kèm chứng chỉ.
  4. Cấu hình OAuth, API key hoặc Bearer token riêng trong Authorization.

Giữ tách biệt giữa TLS certificate và HTTP authorization sẽ giúp bạn xác định lỗi handshake nhanh hơn và cấu hình mTLS ổn định hơn.

Tải Apidog, thêm chứng chỉ của đối tác và gửi request mTLS đầu tiên của bạn. Dùng thử miễn phí, không cần thẻ tín dụng.

Top comments (0)