Apidogでクライアント証明書 (mTLS) が必要なAPIをテストする方法

パートナーAPIを呼び出し、有効なトークンで適切にフォーマットされたリクエストを送信しても、TLSハンドシェイクエラーが発生することがあります。エンドポイントはAPIキーを求めているのではありません。HTTPリクエストがマシンを離れる前に、クライアントに対して証明書で身元を証明するよう求めているのです。これが相互TLSであり、テストツールで設定したことがない場合、統合が1日停止してしまう可能性があります。

このガイドでは、Apidogでのクライアント証明書とCA証明書の設定について説明します。これにより、ハンドシェイクに苦労することなくmTLSで保護されたAPIをテストできます。特定のホストにクライアント証明書とキーを追加し、自己署名ルートによるエラーを防ぐためにCA証明書を添付し、Apidogが自動的に署名する認証済みリクエストを送信します。証明書エラーが初めての場合は、このガイドと一緒にSSL証明書の検証に関する入門書を読む価値があります。プロトコル自体については、MDN TLSリファレンスが信頼できるベンダーニュートラルな解説書です。

ボタン

相互TLSとは何か、なぜ一部のAPIがそれを要求するのか

通常のHTTPSは一方的な信頼です。サーバーが証明書を提示し、クライアントがそれを検証し、接続が暗号化されます。サーバーはあなたが誰であるかという暗号的な証明を持っていません。そのために、リクエスト内のトークンやAPIキーに依存しています。

相互TLSは信頼を双方向にします。サーバーは引き続き自身の証明書を提示しますが、クライアントにも証明書の提示を求めます。サーバーが信頼する認証局によって証明書が署名されていない場合、ハンドシェイクは失敗し、接続は開かれません。リクエストボディもヘッダーも、何も通過しません。

漏洩したベアラートークンが許容できる失敗モードではない場合、相互TLS（mTLS）認証に遭遇します。例えば、以下のようなケースです。

銀行および決済。 オープンバンキングAPIやカード決済処理業者は、OAuthに加えて、組織に発行されたクライアント証明書を要求することがよくあります。Stripeのドキュメントでは、機密性の高い金融エンドポイント向けのこの種の階層型認証情報モデルについて説明しています。
内部およびサービス間トラフィック。 ゼロトラストネットワークを運用する企業は、ネットワーク境界を信頼する代わりに、サービスに証明書で身元を証明させます。
B2BパートナーAPI。 パートナーはオンボーディング中にクライアント証明書を発行し、登録されたマシンのみがエンドポイントにアクセスできるようにする場合があります。

OAuthも使用されている場合、両者はきれいに組み合わされます。RFC 8705は、相互TLSがOAuthトークンをクライアント証明書にバインドする方法を形式化しています。証明書はネットワーク層の認証情報であり、リクエスト内のアプリケーション層の認証とは別物です。この区別はApidogで重要であり、人々が最も混乱しやすい点です。証明書はmTLSを処理します。AuthorizationタブはAPIキー、ベアラートークン、OAuth、およびBasic認証を処理します。両方を同時に必要とすることがよくありますが、設定する場所は異なります。

Apidogがホストごとに証明書をスコープする方法

ApidogはCA証明書とクライアント証明書の両方を扱い、リクエストごとではなくグローバルに設定します。一度証明書を設定し、それをホストに紐付けると、Apidogはそのホストに一致するすべてのHTTPSリクエストに自動的に添付します。リクエストごとに覚えておくべきトグルや貼り付けるヘッダーはありません。

2種類の証明書はそれぞれ異なる役割を果たします。

クライアント証明書は、相互TLS認証のためにあなたの身元を証明するために提示するものです。これはパートナーAPIが要求する認証情報です。
CA証明書は、Apidogがまだ知らない認証局を信頼するようにApidogに伝えます。これを内部ルートCAに向ければ、Apidogがその認証局によって署名されたエンドポイントを信頼するようになるため、恐ろしいSSL Error: Self signed certificateは解消されます。

スコープの鍵はホストです。すべてのクライアント証明書はドメインにバインドされており、Apidogは送信リクエストのホストをそのバインドと照合します。ホストが正しければ、他のすべては自動的に行われます。間違っている場合、Apidogは一致するものを見つけられないため、何も送信しません。

mTLS API用のクライアント証明書をセットアップする

シナリオは次のとおりです。決済パートナーであるpartner-api.acmebank.comは、オンボーディング中にクライアント証明書と秘密鍵を発行しました。彼らのAPIはHTTPSのみであり、その証明書を提示できないクライアントは拒否します。あなたはGET /v1/settlementsを呼び出し、その応答を検査したいと考えています。

ステップ1: 証明書設定を開く

右上の設定アイコンを使用してApidogの設定を開き、Certificatesタブに移動します。ここには両方の証明書タイプが格納されています。ここでの設定は単一のリクエストに縛られるものではなく、ホストマッチングに基づいてすべてのリクエストに適用されます。

ステップ2: クライアント証明書を追加する

Client Certificatesの下で、Add Certificateを選択します。ホストバインディングと証明書ファイルのフォームが開きます。

Hostフィールドには、プロトコルなしでドメインのみを入力します。

partner-api.acmebank.com

https://は省略します。このフィールドは裸のドメインを受け入れます。複数のサブドメインをカバーするために1つの証明書が必要な場合、ホストフィールドはパターンマッチングをサポートしています。*.acmebank.comと入力すると、acmebank.com配下のすべてのサブドメインに同じクライアント証明書が使用されます。これは、パートナーがpartner-api、sandbox-api、settlements-apiを同じ発行済み証明書で運用している場合に便利です。

カスタムポートはオプションです。空白のままにすると、Apidogはデフォルトで標準HTTPSポートである443を使用します。mTLSエンドポイントが他の場所（例えば8443）でリッスンしている場合にのみポートを設定してください。

ステップ3: 証明書ファイルを選択する

Apidogはクライアント証明書に対して2つのファイル形式を受け入れます。パートナーから提供されたいずれかを選択してください。

CRT + キーファイル。 個別の証明書ファイルと秘密鍵ファイルです。それぞれのフィールドで選択してください。
PFXファイル。 証明書と鍵が一緒にバンドルされた単一のファイルです。

証明書がパスフレーズ付きで生成された場合は、パスフレーズフィールドに入力します。これはオプションなので、キーがパスワードで保護されていない場合は空白のままにしてください。銀行からの典型的なオンボーディングバンドルは、.crtと.keyのペアとして提供され、時にはキーにパスフレーズが付いています。

ステップ4: 保存する

Addを選択してクライアント証明書を保存します。これでリストに表示され、partner-api.acmebank.comにバインドされます。この時点から、リクエストごとに証明書を操作する必要はありません。

ステップ5: 認証済みリクエストを送信する

ホストにリクエストを作成して送信します。

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

Apidogはホストと一致させ、TLSハンドシェイク中にクライアント証明書を添付し、リクエストが送信される前に相互TLS認証を完了します。パートナーがOAuthも要求する場合、そのベアラートークンは通常通りリクエストに含まれます。証明書はマシンを証明し、トークンは呼び出し元を証明します。成功した応答は次のようになります。

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

リクエストごとの手動操作でこれが行われたのではありません。ホストマッチングがそうさせたのです。

内部または自己署名ルート用のCA証明書を追加する

クライアント証明書は話の半分に過ぎません。もう半分は、サーバー自身の証明書が、あなたのマシンが信頼しない認証局によって署名されている場合に発生します。これは、プライベートなルートCAを使用する内部サービスやステージング環境でよく見られます。

そのような場合、mTLSが実行される前に、リクエストはSSL Error: Self signed certificateのようなメッセージとともに失敗します。この問題を解決するには、ApidogにCAを渡し、そのルートを信頼させることです。

同じCertificatesタブで、CA Certificatesの横にあるトグルをオンにし、PEMファイルを選択します。CA証明書はPEM形式を使用し、単一のPEMファイルに複数のCA証明書を含めることができるため、内部ルートと中間証明書のチェーン全体を1つのファイルにバンドルできます。

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

CAが信頼されると、ApidogはそのCAによって署名されたエンドポイントを拒否しなくなります。信頼されたCAとクライアント証明書を組み合わせることで、プライベートなルートを使用する内部mTLSサービスをエンドツーエンドでテストできます。CAによって彼らのサーバーを信頼し、クライアント証明書によって彼らがあなたを信頼するようになります。

高度なヒントと一般的なバリエーション

基本的なセットアップが完了すれば、いくつかのことで時間を節約できます。

1つの証明書でサブドメインをカバー。 パートナーがワイルドカードスコープの証明書を発行した場合、partner-api、sandbox-apiなどを個別に登録する代わりに、ホストを*.acmebank.comと一度設定します。1つのバインドですべてのサブドメインをカバーします。
非標準ポート。 内部mTLSゲートウェイは8443や9443のようなポートを好みます。デフォルトは443なので、エンドポイントが別の場所でリッスンしている場合は必ずカスタムポートを指定してください。そうしないとホストが一致せず、証明書が送信されません。
証明書は追加後に編集できません。 編集アクションはありません。更新された証明書をローテーションしたり、ホストのタイプミスを修正したりするには、削除アイコンで既存のものを削除し、再度追加してください。編集ボタンがないことを誰もが探さないように、証明書ローテーションのランブックに組み込んでおきましょう。
1ドメインにつき1つの証明書。 同じドメインに2つのクライアント証明書を登録しないでください。各バインドはドメイン固有であり、重複するとApidogがどちらを提示すべきか曖昧になります。ホストごとに1つにしてください。
証明書と認可は頭の中で分けて考える。 これが最大の混乱の原因です。mTLSはCertificatesタブにあります。APIキー、ベアラートークン、OAuth、Basic認証はリクエストまたはフォルダのAuthorizationタブにあり、リクエストは親フォルダから認可を継承します。認可は、個々のリクエスト、フォルダ内のすべてのリクエスト、コレクション内のすべてのリクエストの3つのレベルで適用されます。パートナーがクライアント証明書とOAuthの両方を必要とする場合、証明書はCertificatesで、トークンはAuthorizationで設定します。これらは重複しません。トークンベースの認証の設定についてさらに詳しく知りたい場合は、APIゲートウェイ認証ガイドがリクエスト側をカバーしており、Windows中心のスタックを扱っている場合は、ApidogでのKerberos認証の設定という関連するチュートリアルもブックマークする価値があります。
常にHTTPSのみ。 Apidogは平文のHTTPリクエストにクライアント証明書を添付しません。テスト対象がhttp://の場合、証明書は決して送信されず、ハンドシェイクロジックも実行されません。このすべてを適用するには、エンドポイントがHTTPSである必要があります。

Apidog CLIでワークフローを自動化する

mTLSリクエストを手動でパスさせたら、それらを保存されたテストシナリオに組み込み、Apidog CLIでヘッドレスで実行します。インストールして認証します。

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

次に、保存されたシナリオを環境に対して実行します。

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

apidog runコマンドはクライアント証明書の設定を直接サポートしているため、mTLSはGUIからパイプラインへの移行でも機能します。単一の証明書の場合、--ssl-client-cert（PEM証明書）、--ssl-client-key（秘密鍵）、およびキーにパスフレーズがある場合は--ssl-client-passphraseを渡します。追加の信頼されたCAには--ssl-extra-ca-certsを指定し、URLパターンで証明書をホストに一致させる場合は設定ファイルとともに--ssl-client-cert-listを使用します。レポーターは-rで設定します（-r html,cliを試してみてください）。このコマンドをジョブに組み込めば、プッシュごとに証明書で保護されたAPIがテストされます。CI/CDにおけるApidog CLIガイドでは、パイプライン内での実行について説明しています。

よくある質問

クライアント証明書とCA証明書の両方が必要ですか、それともどちらか一方ですか？

エンドポイントによります。クライアント証明書はあなたの身元を証明するため、サーバーが相互TLSを要求する際には常に必要です。CA証明書は、サーバー自身の証明書が、内部ルートCAなど、あなたのマシンがまだ信頼していない認証局によって署名されている場合にのみ必要です。信頼できる公開CA上にある公開パートナーAPIはクライアント証明書のみを必要としますが、プライベートなルート上の内部mTLSサービスは通常、両方を必要とします。

Apidogがクライアント証明書を送信しないのはなぜですか？

ほとんどの場合、ホストの不一致または平文HTTPターゲットが原因です。Hostフィールドにhttps://プレフィックスなしの正確なドメインが入力されていること、ポートが一致していること（デフォルトは443なので、エンドポイントが別の場所でリッスンしている場合はカスタムポートを設定してください）、そしてリクエストURLがHTTPSであることを確認してください。ApidogはHTTPリクエストに証明書を添付することはありません。

APIキーとベアラートークンは、Certificatesにない場合、どこに設定しますか？

証明書の設定とは別に、リクエストまたはフォルダのAuthorizationタブに設定します。証明書はTLS層のIDを処理し、Authorizationはリクエスト層でAPIキー、ベアラートークン、OAuth、Basic認証を処理します。セキュリティスキームガイドで認証タイプの完全な内訳を確認でき、フォルダまたはコレクションレベルで一度認証を設定すれば、すべてのリクエストがそれを継承できます。

1つの証明書で複数のサブドメインをカバーできますか？

はい、できます。ホストフィールドはパターンマッチングをサポートしています。*.example.comと入力すると、example.comのすべてのサブドメインに同じクライアント証明書が適用されます。これは、パートナーが複数のAPIサブドメイン用に発行したワイルドカードスコープの証明書を再利用するのに簡潔な方法です。

証明書を追加した後、更新するにはどうすればよいですか？

証明書は追加後にその場で編集することはできません。削除アイコンで既存のものを削除し、修正または更新されたバージョンを再度追加してください。証明書のローテーションの際にはこの点を念頭に置いてください。テストセットアップを整理する際には、Apidogでグローバルパラメータを設定すると、リクエスト全体で環境値をきれいに保つことができます。

まとめ

mTLSで保護されたAPIのテストは、Apidogで3つの手順に集約されます。クライアント証明書を適切なホストにバインドし、サーバーがプライベートルートを使用している場合はCA証明書を添付し、ホストマッチングによってすべてのHTTPSリクエストを自動的に署名させます。証明書と認可をそれぞれの役割に保てば、ハンドシェイクはもはや謎ではなくなります。

Apidogをダウンロードして、このガイドに従い、パートナーの証明書を追加し、最初の認証済みリクエストを送信してください。無料で試すことができ、クレジットカードは不要です。