Blog

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

Tìm hiểu cách kiểm thử API yêu cầu chứng chỉ máy khách (mTLS) trong Apidog: thêm chứng chỉ và khóa máy khách cho mỗi máy chủ, đính kèm chứng chỉ CA và gửi các yêu cầu đã xác thực.

INEZA Felin-Michel

INEZA Felin-Michel

16 tháng 7 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Bạn truy cập một API đối tác, gửi một yêu cầu đúng định dạng với token hợp lệ, nhưng vẫn gặp lỗi bắt tay TLS (TLS handshake failure). Điểm cuối (endpoint) không yêu cầu khóa API của bạn. Nó yêu cầu client của bạn chứng minh danh tính bằng một chứng chỉ, trước cả khi bất kỳ yêu cầu HTTP nào rời khỏi máy của bạn. Đó chính là TLS song phương (mutual TLS), và nếu bạn chưa bao giờ cấu hình nó trong một công cụ kiểm thử, nó có thể làm chậm quá trình tích hợp cả một ngày.

Hướng dẫn này sẽ chỉ cho bạn cách thiết lập chứng chỉ client và chứng chỉ CA trong Apidog để bạn có thể kiểm tra một API được bảo vệ bằng mTLS mà không gặp rắc rối với quá trình bắt tay. Bạn sẽ thêm một chứng chỉ client và khóa cho một host cụ thể, đính kèm một chứng chỉ CA để các root tự ký không còn gây lỗi, và gửi một yêu cầu đã xác thực mà Apidog tự động ký. Nếu lỗi chứng chỉ là một lĩnh vực mới mẻ, bài giới thiệu về xác minh chứng chỉ SSL rất đáng đọc cùng với hướng dẫn này. Đối với bản thân giao thức, tài liệu tham khảo TLS của MDN là một giải thích vững chắc, trung lập về nhà cung cấp.

nút

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

HTTPS thông thường là sự tin cậy một chiều. Máy chủ trình bày một chứng chỉ, client của bạn xác minh nó, và kết nối được mã hóa. Máy chủ không có bằng chứng mật mã về danh tính của bạn; nó dựa vào một token hoặc khóa API bên trong yêu cầu để thực hiện điều đó.

TLS song phương (Mutual TLS) làm cho sự tin cậy đi theo cả hai chiều. Máy chủ vẫn trình bày chứng chỉ của mình, nhưng nó cũng yêu cầu client trình bày một chứng chỉ. Nếu chứng chỉ của bạn không được ký bởi một tổ chức cấp chứng chỉ mà máy chủ tin cậy, quá trình bắt tay sẽ thất bại và kết nối sẽ không bao giờ được mở. Không có nội dung yêu cầu, không có tiêu đề, không có gì được truyền qua.

Bạn sẽ gặp xác thực TLS song phương (mTLS) ở những nơi mà việc lộ token bearer không phải là một chế độ lỗi chấp nhận được:

Nếu OAuth cũng được sử dụng, hai loại này kết hợp một cách rõ ràng; RFC 8705 chính thức hóa cách TLS song phương liên kết token OAuth với chứng chỉ client. Chứng chỉ là thông tin xác thực cấp mạng (network-layer credential), tách biệt với xác thực cấp ứng dụng (application-layer auth) trong yêu cầu của bạn. Sự phân biệt đó quan trọng trong Apidog, và đây là điều mà mọi người thường hay nhầm lẫn nhất. Chứng chỉ xử lý mTLS. Tab Authorization xử lý các khóa API, token bearer, OAuth và Basic auth. Bạn thường cần cả hai cùng một lúc, nhưng bạn cấu hình chúng ở những nơi khác nhau.

Cách Apidog giới hạn phạm vi chứng chỉ theo host

Apidog xử lý cả chứng chỉ CA và chứng chỉ client, và nó cấu hình chúng ở phạm vi toàn cục chứ không phải theo từng yêu cầu. Bạn thiết lập một chứng chỉ một lần, liên kết nó với một host, và Apidog sẽ tự động đính kèm nó vào mỗi yêu cầu HTTPS phù hợp với host đó. Không có nút bật/tắt theo yêu cầu nào cần nhớ và không có tiêu đề nào cần dán.

Hai loại chứng chỉ thực hiện hai công việc khác nhau:

Khóa phạm vi là host. Mỗi chứng chỉ client được ràng buộc với một tên miền, và Apidog so khớp host của yêu cầu gửi đi với ràng buộc đó. Thiết lập đúng host và mọi thứ khác sẽ tự động. Thiết lập sai và Apidog sẽ âm thầm không gửi gì, vì nó không tìm thấy sự phù hợp.

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

Đây là kịch bản. Một đối tác thanh toán, partner-api.acmebank.com, đã cấp cho bạn một chứng chỉ client và khóa riêng trong quá trình giới thiệu. API của họ chỉ hỗ trợ HTTPS và từ chối bất kỳ client nào không thể trình bày chứng chỉ đó. Bạn muốn gọi GET /v1/settlements và kiểm tra phản hồi.

Bước 1: Mở cài đặt Chứng chỉ

Mở cài đặt Apidog bằng cách sử dụng biểu tượng cài đặt ở trên cùng bên phải, sau đó chuyển đến tab **Certificates**. Đây là nơi chứa cả hai loại chứng chỉ. Không có gì ở đây bị ràng buộc với một yêu cầu duy nhất; nó áp dụng cho tất cả các yêu cầu của bạn dựa trên việc khớp host.

Bước 2: Thêm chứng chỉ client

Dưới mục **Client Certificates**, chọn **Add Certificate**. Một biểu mẫu sẽ mở ra để ràng buộc host và các tệp chứng chỉ.

Điền vào trường **Host** chỉ với tên miền, không có giao thức:

partner-api.acmebank.com

Bỏ qua https://. Trường này chỉ nhận tên miền trần. Nếu bạn cần một chứng chỉ để bao phủ nhiều subdomain, trường host hỗ trợ khớp mẫu. Nhập *.acmebank.com sẽ sử dụng cùng một chứng chỉ client cho mọi subdomain dưới acmebank.com, điều này rất tiện lợi khi một đối tác chạy partner-api, sandbox-api, và settlements-api từ cùng một chứng chỉ đã cấp.

Cổng tùy chỉnh là tùy chọn. Để trống và Apidog sẽ mặc định là 443, cổng HTTPS tiêu chuẩn. Chỉ đặt cổng nếu điểm cuối mTLS lắng nghe ở một nơi khác, ví dụ 8443.

Bước 3: Chọn các tệp chứng chỉ

Apidog chấp nhận hai bố cục tệp cho chứng chỉ client. Chọn bất kỳ loại nào mà đối tác của bạn đã cung cấp:

Nếu chứng chỉ được tạo bằng cụm mật khẩu (passphrase), hãy nhập nó vào trường **passphrase**. Đây là tùy chọn, vì vậy hãy để trống nếu khóa của bạn không được bảo vệ bằng mật khẩu. Một gói giới thiệu điển hình từ ngân hàng thường bao gồm một cặp .crt và .key, đôi khi có cụm mật khẩu trên khóa.

Bước 4: Lưu

Chọn **Add** để lưu chứng chỉ client. Nó giờ đây sẽ xuất hiện trong danh sách của bạn, được ràng buộc với partner-api.acmebank.com. Từ thời điểm này trở đi, bạn sẽ không cần phải động đến nó nữa cho mỗi yêu cầu.

Bước 5: Gửi yêu cầu đã xác thực

Tạo một yêu cầu đến host và gửi nó:

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

Apidog khớp host, đính kèm chứng chỉ client của bạn trong quá trình bắt tay TLS, và hoàn tất xác thực TLS song phương trước khi yêu cầu được gửi đi. Nếu đối tác cũng yêu cầu OAuth, token bearer đó sẽ được gửi trong yêu cầu như bình thường. Chứng chỉ chứng minh máy; token chứng minh người gọi. Một phản hồi thành công có thể trông như thế này:

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

Không có bước thủ công nào cho mỗi yêu cầu đã tạo ra điều đó. Sự khớp host đã làm điều đó.

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

Chứng chỉ client chỉ là một nửa câu chuyện. Nửa còn lại xuất hiện khi chứng chỉ của chính máy chủ được ký bởi một tổ chức mà máy của bạn không tin cậy, điều này phổ biến với các dịch vụ nội bộ và môi trường staging sử dụng CA gốc riêng tư.

Khi điều đó xảy ra, yêu cầu sẽ thất bại với thông báo như SSL Error: Self signed certificate trước cả khi mTLS có cơ hội. Cách khắc phục là cung cấp CA cho Apidog để nó tin tưởng root đó.

Trong cùng tab **Certificates**, bật nút chuyển đổi bên cạnh **CA Certificates**, sau đó chọn tệp PEM của bạn. Chứng chỉ CA sử dụng định dạng PEM, và một tệp PEM duy nhất có thể chứa nhiều chứng chỉ CA, vì vậy bạn có thể gói toàn bộ chuỗi các root và intermediate nội bộ vào một tệp:

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

Khi CA được tin cậy, Apidog sẽ ngừng từ chối các điểm cuối được ký bởi nó. Kết hợp một CA đáng tin cậy với một chứng chỉ client và bạn có thể kiểm tra một dịch vụ mTLS nội bộ sử dụng một root riêng tư từ đầu đến cuối: CA cho phép bạn tin tưởng máy chủ của họ, và chứng chỉ client cho phép họ tin tưởng bạn.

Mẹo nâng cao và các biến thể phổ biến

Một vài điều sẽ giúp bạn tiết kiệm thời gian khi bạn đã hoàn tất thiết lập cơ bản.

Tự động hóa quy trình làm việc với Apidog CLI

Khi các yêu cầu mTLS của bạn đã chạy thành công thủ công, hãy đưa chúng vào các kịch bản kiểm thử đã lưu và chạy chúng không giao diện người dùng (headless) với Apidog CLI. Cài đặt và xác thực:

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

Sau đó chạy một kịch bản đã lưu trên một môi trường:

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

Lệnh apidog run hỗ trợ cấu hình chứng chỉ client trực tiếp, vì vậy mTLS vẫn hoạt động khi chuyển từ giao diện người dùng đồ họa (GUI) sang pipeline. Đối với một chứng chỉ duy nhất, hãy truyền --ssl-client-cert (chứng chỉ PEM), --ssl-client-key (khóa riêng), và --ssl-client-passphrase nếu khóa có mật khẩu. Trỏ --ssl-extra-ca-certs đến các CA đáng tin cậy bổ sung, hoặc sử dụng --ssl-client-cert-list với một tệp cấu hình khi bạn khớp chứng chỉ với host bằng mẫu URL. Các trình báo cáo (reporters) được thiết lập bằng -r (thử -r html,cli). Gắn lệnh đó vào một tác vụ và API được bảo vệ bằng chứng chỉ của bạn sẽ được kiểm tra trên mỗi lần đẩy. Hướng dẫn Apidog CLI trong CI/CD bao gồm việc chạy nó bên trong một pipeline.

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

Tôi có cần chứng chỉ client và chứng chỉ CA, hay chỉ cần một trong hai?

Tùy thuộc vào điểm cuối. Chứng chỉ client chứng minh danh tính của bạn, vì vậy bạn cần nó bất cứ khi nào máy chủ yêu cầu TLS song phương. Chứng chỉ CA chỉ cần thiết khi chứng chỉ của chính máy chủ được ký bởi một tổ chức mà máy của bạn chưa tin cậy, chẳng hạn như một CA gốc nội bộ. Một API đối tác công khai trên một CA công khai đáng tin cậy chỉ cần chứng chỉ client; một dịch vụ mTLS nội bộ trên một root riêng tư thường cần cả hai.

Tại sao Apidog không gửi chứng chỉ client của tôi?

Hầu như luôn là do host không khớp hoặc mục tiêu là HTTP thuần túy. Kiểm tra xem trường Host có chứa chính xác tên miền mà không có tiền tố https://, rằng cổng khớp (mặc định là 443, vì vậy hãy đặt cổng tùy chỉnh nếu điểm cuối lắng nghe ở nơi khác), và rằng URL yêu cầu là HTTPS. Apidog không bao giờ đính kèm chứng chỉ vào một yêu cầu HTTP.

Khóa API và token bearer nằm ở đâu nếu không phải trong Chứng chỉ?

Trong tab Authorization của yêu cầu hoặc thư mục, tách biệt với thiết lập chứng chỉ. Chứng chỉ xử lý danh tính lớp TLS; Ủy quyền xử lý Khóa API, Token Bearer, OAuth và Basic auth ở lớp yêu cầu. Bạn có thể tìm thấy toàn bộ phân tích các loại xác thực trong hướng dẫn sơ đồ bảo mật, và bạn có thể thiết lập xác thực một lần ở cấp độ thư mục hoặc bộ sưu tập để mọi yêu cầu kế thừa nó.

Một chứng chỉ có thể bao phủ nhiều subdomain không?

Có. Trường host hỗ trợ khớp mẫu. Nhập *.example.com và cùng một chứng chỉ client sẽ áp dụng cho mọi subdomain của example.com. Đó là cách rõ ràng để sử dụng lại một chứng chỉ phạm vi ký tự đại diện (wildcard-scoped) mà một đối tác đã cấp cho một số subdomain API của họ.

Làm cách nào để cập nhật chứng chỉ sau khi nó được thêm vào?

Chứng chỉ không thể chỉnh sửa trực tiếp. Xóa chứng chỉ hiện có bằng biểu tượng xóa, sau đó thêm phiên bản đã sửa hoặc đã gia hạn. Hãy nhớ điều đó cho việc xoay vòng chứng chỉ, và trong khi bạn đang tổ chức các thiết lập kiểm thử, việc thiết lập các tham số toàn cục trong Apidog rất phù hợp để giữ các giá trị môi trường gọn gàng giữa các yêu cầu.

Tổng kết

Kiểm tra một API được bảo vệ bằng mTLS trong Apidog gói gọn trong ba bước: liên kết chứng chỉ client với host phù hợp, đính kèm chứng chỉ CA nếu máy chủ sử dụng một root riêng, và để tính năng khớp host tự động ký mọi yêu cầu HTTPS. Giữ chứng chỉ và Ủy quyền (Authorization) ở các phần riêng biệt và quá trình bắt tay sẽ không còn là một bí ẩn.

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

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống