Oracle Cloud Infrastructureドキュメント

HTTPSバックエンドTLSハンドシェイクが失敗する

APIゲートウェイ・サービスを使用してAPIデプロイメントを作成するときに、HTTPSバックエンドTLSハンドシェイク障害をトラブルシューティングする方法をご紹介します。

APIデプロイメントでHTTPSバックエンドを使用する場合、TLSハンドシェイク障害によって、バックエンド・サービスがHTTPトラフィックを処理する前にリクエストを停止できます。通常、失敗は、APIゲートウェイがバックエンドによって提示された証明書チェーンまたはTLS構成を検証できないことを意味します。

問題の症状

次の症状が1つ以上表示される場合があります。

  • バックエンドURLは正しいが、バックエンド・サービスがHTTPリクエストを処理する前にリクエストが失敗する。

  • 実行ログには、httpBackend.requestErrorログ・コードが表示されます。

  • 実行ログ・メッセージはHANDSHAKE_FAILEDで終了します。

  • バックエンド・サービスがプライベート認証局(CA)、カスタムCAバンドルまたはAPIゲートウェイが信頼しない証明書チェーンを使用している場合、リクエストは失敗します。

考えられる理由

HTTPSバックエンドTLSハンドシェイク障害には通常、次のいずれかの原因があります。

  • バックエンド証明書の有効期限が切れているか、不完全であるか、無効です。

  • バックエンド証明書チェーンに中間証明書がありません。

  • 証明書チェーンは、APIゲートウェイ・トラスト・ストアにないCAを使用します。

  • サポートされていないTLS設定や正しくないTLS設定など、バックエンドTLSリスナーが正しく構成されていません。

  • APIゲートウェイがバックエンドにHTTPリクエストを送信する前に、TLSセッションが失敗します。

ログ・メッセージのレビュー

APIゲートウェイを介してリクエストを繰り返し、同じリクエストの実行ログを確認します。

リクエストを繰り返すには、次のコマンドを使用します。

  • curl -i https://<gateway-hostname>/<deployment-path-prefix>/<api-route-path>

「ロギング」で、次のログ詳細を確認します。

  • 失敗したリクエストのopc-request-idを取得します。

  • 同じリクエストの実行ログを開きます。

  • ログ・コードがhttpBackend.requestErrorであるかどうかを確認します。

  • メッセージがHANDSHAKE_FAILEDで終わるかどうかを確認します。

次のログ・メッセージは、ゲートウェイがHTTPリクエストをバックエンドに送信する前にTLSハンドシェイクに失敗したことを示しています。

  • An error occurred whilst sending request to https://<backend-url>: HANDSHAKE_FAILED

HTTPSバックエンド構成の確認

失敗したリクエストのルートおよびバックエンド構成を確認します。

  • backend.urlが予想されるHTTPSバックエンドを指していることを確認します。

  • バックエンド・リスナーに完全な証明書チェーンが示されていることを確認します。

  • バックエンドでプライベートCAまたはカスタムCAバンドルが使用されている場合は、APIゲートウェイ・トラスト・ストアに必要なCAまたはCAバンドルが含まれていることを確認します。

  • TLSリスナー構成が、APIデプロイメントのHTTPSバックエンドおよびトラストストアの要件と一致していることを確認します。

HTTPSバックエンドの直接検証

バック・エンドに直接到達できるシステムから、APIゲートウェイ外部のHTTPSリスナーをテストします。

TLSハンドシェイクを調べるには、次のコマンドを使用します。

  • curl -v <backend-url>

次の詳細については、直接テストの結果を確認してください。

  • バックエンド・リスナーが示す証明書チェーン。

  • 証明書の有効期限およびホスト名の範囲。

  • TLSプロトコルおよび暗号構成。

  • HTTPリクエストが送信される前に発生した証明書検証エラー。

HTTPSバックエンドTLSの問題の修正

見つかった問題と一致する修正を適用します。

  • バックエンド証明書の有効期限が切れているか、不完全であるか、無効である場合、証明書チェーンを置換または修正します。

  • 証明書チェーンに中間証明書がない場合は、バックエンド・リスナーを構成して完全なチェーンを表示します。

  • バックエンドがプライベートCAまたはカスタムCAバンドルを使用する場合は、必要なCAまたはCAバンドルをAPIゲートウェイ・トラスト・ストアに追加します。

  • バックエンド・リスナーで不正なTLS設定が使用されている場合は、リスナー構成を更新し、リクエストを再試行してください。

  • 実行ログにhttpBackend.requestErrorとHANDSHAKE_FAILEDが表示されている場合は、APIゲートウェイ・ルート構成を変更する前にHTTPSリスナーをトラブルシューティングします。

HTTPSバックエンド接続の検証

TLS構成を修正したら、APIデプロイメントがHTTPSバックエンドに到達できることを確認します。

  • APIゲートウェイを介して同じリクエストを送信します。

  • 実行ログにhttpBackend.requestErrorとHANDSHAKE_FAILEDが表示されなくなったことを確認します。

  • バックエンド・サービスがHTTPリクエストを受信して処理することを確認します。

詳細情報

詳細は、次を参照してください: