DEV Community

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

Posted on • Originally published at apidog.com

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

パートナーAPIを呼び出し、有効なトークンと正しいリクエスト形式を使っていても、TLSハンドシェイクエラーが発生することがあります。これはAPIキーの問題ではないかもしれません。HTTPリクエストがマシンを離れる前に、クライアント証明書で身元を証明するようサーバーが要求している可能性があります。これが相互TLS（mTLS）です。設定方法を知らないと、統合作業が止まる原因になります。

今すぐApidogを試す

この記事では、Apidogでクライアント証明書とCA証明書を設定し、mTLSで保護されたAPIをテストする手順を解説します。特定ホストにクライアント証明書と秘密鍵を紐付け、必要に応じてCA証明書を追加し、認証済みリクエストを送信します。証明書エラーに初めて対応する場合は、SSL証明書の検証も確認してください。TLSそのものについては、MDN TLSリファレンスが参考になります。

相互TLS（mTLS）とは

通常のHTTPSでは、サーバーだけが証明書を提示します。クライアントはその証明書を検証し、暗号化された接続を開始します。一方、サーバーはクライアントの暗号学的な身元を確認しないため、APIキーやベアラートークンなどで呼び出し元を認証します。

mTLSでは、サーバーとクライアントの双方が証明書を提示します。

  1. サーバーがサーバー証明書を提示する
  2. クライアントがサーバー証明書を検証する
  3. サーバーがクライアント証明書を要求する
  4. クライアントが証明書と秘密鍵を使って身元を証明する
  5. サーバーが信頼できるCAによる署名を確認する

クライアント証明書が信頼されない場合、TLSハンドシェイクは失敗します。この段階ではHTTPヘッダーやリクエストボディはまだ送信されません。

mTLSは、たとえば次のような場面で使われます。

  • 銀行・決済API: OAuthに加え、組織に発行されたクライアント証明書を要求するケースがあります。Stripeのドキュメントでも、機密性が高い金融エンドポイント向けの階層型認証情報モデルが説明されています。
  • 内部サービス間通信: ゼロトラスト環境では、ネットワーク境界ではなく証明書でサービスの身元を確認します。
  • B2BパートナーAPI: オンボーディング時に発行されたクライアント証明書を持つシステムだけにアクセスを許可します。

OAuthとmTLSは併用できます。RFC 8705では、OAuthトークンをクライアント証明書にバインドする仕組みが定義されています。

ここで重要なのは、証明書とAPI認可は別のレイヤーだという点です。

設定対象 役割 Apidogでの設定場所
クライアント証明書 TLS層でクライアントの身元を証明する Certificates
CA証明書 サーバー証明書の発行元を信頼する Certificates
APIキー、Bearerトークン、OAuth、Basic認証 HTTPリクエストを認可する Authorization

Authorizationの設定だけではmTLSを通過できません。mTLSとOAuthの両方が必要なAPIでは、両方を設定します。

Apidogの証明書設定はホスト単位で適用される

Apidogでは、CA証明書とクライアント証明書をリクエストごとではなくグローバルに設定します。証明書をホストに紐付けると、そのホストに一致するHTTPSリクエストへ自動的に適用されます。

証明書にはそれぞれ異なる役割があります。

  • クライアント証明書: mTLSでサーバーに提示し、クライアントの身元を証明します。
  • CA証明書: Apidogが未信頼の認証局を信頼するために使います。内部ルートCAを追加すると、SSL Error: Self signed certificate を回避できます。

ホスト設定が正確であることが重要です。登録したホストとリクエスト先ホストが一致すれば、Apidogが自動的に証明書を添付します。一致しなければ、証明書は送信されません。

mTLS API用のクライアント証明書を設定する

ここでは、決済パートナーの partner-api.acmebank.com を例にします。オンボーディング時にクライアント証明書と秘密鍵を受け取り、次のエンドポイントを呼び出すケースです。

GET /v1/settlements
Enter fullscreen mode Exit fullscreen mode

1. Certificates設定を開く

Apidog右上の設定アイコンを開き、Certificates タブへ移動します。

この画面では、リクエスト単位ではなくホスト単位で証明書を登録します。

2. クライアント証明書を追加する

Client Certificates セクションで Add Certificate を選択します。

Host には、プロトコルなしでドメインだけを入力します。

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

次の形式は使用しません。

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

複数のサブドメインに同じ証明書を適用する場合は、ワイルドカードを使用できます。

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

たとえば、次のホストで同じ証明書を使う場合に有効です。

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

ポートは通常、空欄のままで構いません。デフォルトのHTTPSポートである 443 が使われます。APIが 8443 などの非標準ポートを使う場合だけ、ポートを明示してください。

3. 証明書ファイルを選択する

Apidogでは、クライアント証明書として次の形式を指定できます。

  • CRT + Key: 証明書ファイルと秘密鍵ファイルを別々に指定する形式
  • PFX: 証明書と秘密鍵が1つにまとめられた形式

秘密鍵またはPFXファイルにパスフレーズが設定されている場合は、Passphrase に入力します。保護されていない鍵であれば空欄のままで問題ありません。

一般的なオンボーディング用バンドルは次のような構成です。

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

4. 保存する

Add を選択して保存します。

これで、partner-api.acmebank.com 宛てのHTTPSリクエストには、登録したクライアント証明書が自動的に適用されます。

5. OAuthトークンを含むリクエストを送信する

mTLSに加えてOAuthも必要な場合、通常どおりBearerトークンを設定します。

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

Apidogは次の順序で処理します。

  1. リクエストURLのホストを確認する
  2. 登録済みのクライアント証明書と照合する
  3. TLSハンドシェイク中に証明書を提示する
  4. mTLS認証完了後、HTTPリクエストを送信する
  5. Authorization設定に従ってBearerトークンを送信する

成功時のレスポンス例です。

{
  "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・自己署名ルート用のCA証明書を追加する

クライアント証明書を設定しても、サーバー証明書の発行元が未信頼であれば接続できません。

この問題は、次のような環境でよく起きます。

  • プライベートルートCAを使う内部サービス
  • 自己署名証明書を使う開発・ステージング環境
  • 独自の中間CAを使う企業ネットワーク

代表的なエラーは次のとおりです。

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

この場合は、サーバー証明書を発行したCAをApidogに登録します。

  1. Certificates タブを開く
  2. CA Certificates のトグルをオンにする
  3. PEM形式のCA証明書を選択する

PEMファイルには、ルートCAと中間CAをまとめて含められます。

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

CAを追加すると、ApidogはそのCAが署名したサーバー証明書を信頼できるようになります。

つまり、内部mTLSサービスでは次の2つを設定することがあります。

  • CA証明書: クライアント側がサーバーを信頼するため
  • クライアント証明書: サーバー側がクライアントを信頼するため

実装時のチェックポイント

基本設定後は、次の点を確認してください。

  • サブドメインをまとめて設定する

    同じ証明書を複数サブドメインで使うなら、*.acmebank.com のようなパターンを使います。

  • 非標準ポートを指定する

    8443 や 9443 を使う内部ゲートウェイでは、ホスト設定に正しいポートを指定します。デフォルトは 443 です。

  • 証明書は追加後に編集できない

    証明書更新やホスト修正が必要な場合は、既存の設定を削除して再登録します。証明書ローテーション手順に含めておくと安全です。

  • 同一ドメインには1つの証明書を登録する

    同じドメインに複数のクライアント証明書を登録すると、どれを使うべきか曖昧になります。

  • CertificatesとAuthorizationを混同しない

    mTLSは Certificates、APIキー・Bearerトークン・OAuth・Basic認証は Authorization で設定します。Authorizationはリクエスト、フォルダ、コレクションの各レベルで適用できます。

  • HTTPSのみで動作する

    http:// の平文リクエストにはクライアント証明書は添付されません。mTLSの対象URLは必ず https:// にしてください。

トークンベース認証の設定は、APIゲートウェイ認証も参照してください。Windows中心の環境では、ApidogでのKerberos認証の設定も関連します。

Apidog CLIでmTLSテストを自動化する

GUIでmTLSリクエストを確認したら、保存済みシナリオをCI/CDで実行できます。Apidog CLIをインストールし、アクセストークンで認証します。

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

保存済みシナリオを環境に対して実行します。

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

apidog run では、クライアント証明書関連の設定を直接指定できます。

オプション 用途
--ssl-client-cert PEM形式のクライアント証明書
--ssl-client-key 秘密鍵
--ssl-client-passphrase 秘密鍵のパスフレーズ
--ssl-extra-ca-certs 追加で信頼するCA証明書
--ssl-client-cert-list URLパターンに応じて証明書を切り替える設定ファイル

レポーターは -r で指定できます。

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

CIジョブに組み込めば、pushごとに証明書保護されたAPIを検証できます。パイプラインでの実行方法は、CI/CDにおけるApidog CLIを確認してください。

よくある質問

クライアント証明書とCA証明書は両方必要ですか？

ケースによります。

  • サーバーがmTLSを要求する場合、クライアント証明書は必要です。
  • サーバー証明書が未信頼の内部CAや自己署名CAで署名されている場合、CA証明書も必要です。

公開CAを使う外部パートナーAPIでは、クライアント証明書だけでよい場合があります。内部mTLSサービスでは両方必要になることがあります。

Apidogがクライアント証明書を送信しません

次を確認してください。

  1. Host に https:// を含めていないか
  2. リクエスト先ドメインがHost設定と完全に一致しているか
  3. 非標準ポートを使う場合、ポート設定が一致しているか
  4. リクエストURLが https:// で始まっているか

ApidogはHTTPリクエストにはクライアント証明書を添付しません。

APIキーやBearerトークンはどこに設定しますか？

Certificates ではなく、リクエストまたはフォルダの Authorization タブに設定します。

認証方式の詳細は、セキュリティスキームを参照してください。フォルダまたはコレクションレベルに設定すれば、配下のリクエストに認証設定を継承できます。

1つの証明書を複数サブドメインに使えますか？

はい。Hostフィールドでパターンマッチングを使います。

*.example.com
Enter fullscreen mode Exit fullscreen mode

これにより、example.com 配下のサブドメインに同じクライアント証明書を適用できます。

登録済み証明書を更新するにはどうすればよいですか？

証明書は追加後に直接編集できません。既存の証明書を削除し、更新後のファイルで再登録してください。

テスト設定の環境値を整理するには、Apidogでグローバルパラメータを設定するも役立ちます。

まとめ

ApidogでmTLS APIをテストする手順は次の3つです。

  1. クライアント証明書を対象ホストへ紐付ける
  2. プライベートCAを使うサーバーにはCA証明書を追加する
  3. HTTPSリクエストを送信し、ホストマッチングによる証明書の自動適用を確認する

証明書はTLS層、APIキーやOAuthトークンはHTTP認可層の設定です。この2つを分けて管理すれば、mTLSハンドシェイクエラーを効率的に切り分けられます。

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

Top comments (0)