503 Service Unavailable - SSL handshake エラー

API Monitoring

手順 1: API Monitoring を使用する

API Monitoring を使用してエラーを診断するには:

1. 適切なロールを持つユーザーとして Apigee Edge UI にログインします。

2. 問題の調査対象となる組織に切り替えます。

   
3. [Analyze] > [API Monitoring] > [Investigate] ページに移動します。
4. エラーが発生した特定の期間を選択します。

5. 障害コードと時間をプロットします。

6. 以下に示すように、障害コード messaging.adaptors.http.flow.SslHandshakeFailed が含まれるセルを選択します。

   （ 大きい画像を表示）

   

7. 障害コード messaging.adaptors.http.flow.SslHandshakeFailed に関する情報は、次のように表示されます。

   （ 大きい画像を表示）

   

8. [ログを表示 ] をクリックし、失敗したリクエストの行を開きます。

   （ 大きい画像を表示）

   
9. [ログ] ウィンドウで、次の詳細を確認します。
   • リクエスト メッセージ ID
   • ステータス コード: 503
   • 障害の発生元: target
   • 障害コード: messaging.adaptors.http.flow.SslHandshakeFailed

トレース

手順 2: Trace ツールを使用する

Trace ツールを使用してエラーを診断するには:

1. トレース セッションと、次のいずれかを有効にします。
   • エラーコード messaging.adaptors.http.flow.SslHandshakeFailed の 503 Service Unavailable エラーが発生するまで待つ。
   • 問題を再現できる場合は、API 呼び出しを行って問題を再現します。503 Service Unavailable

2. [Show all FlowInfos] が有効になっていることを確認します。

   
3. 失敗したリクエストのいずれかを選択し、トレースを確認します。
4. トレースのさまざまなフェーズを調べて、障害が発生した場所を特定します。

5. 通常、エラーは次の図に示すように、フェーズ Target Request Flow Started の後に表示されます。

   （ 大きい画像を表示）

   
6. トレースから次の値をメモします。
   • エラー: SSL Handshake failed sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   • error.cause: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   • error.class: com.apigee.errors.http.server.ServiceUnavailableException
   • エラー SSL Handshake failed sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target の値は、Apigee Edge の Message Processor がバックエンド サーバーの証明書を検証できなかったため、SSL ハンドシェイクが失敗したことを示しています。
7. トレースの [AX]（Analytics Data Recorded）フェーズに移動してクリックします。

8. [Phase Details Error Headers] セクションまでスクロールし、次の図に示すように、X-Apigee-fault-code、X-Apigee-fault-source、X-Apigee-Message-ID の値を確認します。

   （ 大きい画像を表示）

   
9. X-Apigee-fault-code、X-Apigee-fault-source、X-Apigee-Message-ID の値をメモします。

エラー ヘッダー	値
X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
X-Apigee-fault-source	target
X-Apigee-Message-ID	MESSAGE_ID

NGINX

手順 3: NGINX アクセスログを使用する

NGINX アクセスログを使用してエラーを診断するには:

1. Private Cloud ユーザーの場合は、NGINX アクセスログを使用して、HTTP 503 Service Unavailable に関する重要な情報を確認できます。

2. NGINX アクセスログを確認します。

   /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

3. 特定の期間にエラーコード messaging.adaptors.http.flow.SslHandshakeFailed の 503 エラーが発生しているかどうか（過去に問題が発生した場合）、または 503 で失敗しているリクエストがまだあるかどうかを検索します。

4. X-Apigee-fault-code が messaging.adaptors.http.flow.SslHandshakeFailed の値と一致する 503 エラーが見つかった場合は、X-Apigee-fault-source の値を特定します。

   NGINX アクセスログの 503 エラーの例:

   （ 大きい画像を表示）

   

   上記の NGINX アクセスログのエントリ例では、X-Apigee-fault-code と X-Apigee-fault-source に次の値が設定されています。

   ヘッダー	値
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

Message Processor ログ

手順 4: Message Processor のログを使用する

1. 一般的な診断手順の説明に従って、API Monitoring、Trace ツール、NGINX アクセスログを使用して、失敗したリクエストのいずれかのメッセージ ID を特定します。

2. Message Processor のログ（/opt/apigee/var/log/edge-message-processor/logs/system.log）で特定のリクエスト メッセージ ID を検索します。次のエラーが表示されることがあります。

   org:myorg env:test api:MyProxy rev:1
   messageid:myorg-28247-3541813-1
   NIOThread@1 ERROR HTTP.CLIENT - HTTPClient$Context.handshakeFailed() :
   SSLClientChannel[Connected: Remote:X.X.X.X:443
   Local:192.168.194.140:55102]@64596 useCount=1
   bytesRead=0 bytesWritten=0 age=233ms  lastIO=233ms
   isOpen=true handshake failed, message: General SSLEngine problem
   

   上記のエラーは、Message Processor とバックエンド サーバーの間で SSL handshake が失敗したことを示しています。

   その後、次のように詳細なスタック トレースを含む例外が続きます。

   org:myorg env:test api:MyProxy rev:1
   messageid:myorg-28247-3541813-1
   NIOThread@1 ERROR ADAPTORS.HTTP.FLOW - RequestWriteListener.onException() :
   RequestWriteListener.onException(HTTPRequest@1522922c)
   javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   	at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1478)
   	at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:535)
   	... <snipped>
   Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   	at sun.security.ssl.Alerts.getSSLException(Alerts.java:203)
   	at sun.security.ssl.SSLEngineImpl.fatal(SSLEngineImpl.java:1728)
   	... <snipped>
   Caused by: sun.security.validator.ValidatorException: PKIX path building failed:
   sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid
   certification path to requested target
   	at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:397)
   	at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:302)
   	... <snipped>
     

   ハンドシェイクの失敗の原因は次のとおりです。

   Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

   これは、Apigee Edge の Message Processor がバックエンド サーバーの証明書を検証できなかったため、SSL handshake が失敗したことを示します。

フェーズ 1

フェーズ 1: バックエンド サーバーの証明書チェーンを特定する

バックエンド サーバーの証明書チェーンを特定するには、次のいずれかの方法を使用します。

openssl s_client -connect BACKEND_SERVER_HOST_NAME:PORT#

Certificate chain
 0 s:/CN=mocktarget.apigee.net
   i:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
 1 s:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
   i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
 2 s:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
   i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1

フェーズ 2

フェーズ 2: バックエンド サーバーの証明書と Message Processor のトラストストアに保存されている証明書を比較する

1. バックエンド サーバーの証明書チェーンを特定します。
2. 次の手順で、メッセージ プロセッサのトラストストアに保存されている証明書を特定します。

   1. TargetEndpoint の SSLInfo セクションの TrustStore 要素からトラストストアの参照名を取得します。

      以下は TargetEndpoint 構成の SSLInfo セクションの例です。

      <TargetEndpoint name="default">
      ...
         <HTTPTargetConnection>
            <Properties />
            <SSLInfo>
               <Enabled>true</Enabled>
               <ClientAuthEnabled>true</ClientAuthEnabled>
               <KeyStore>ref://myKeystoreRef</KeyStore>
               <KeyAlias>myKey</KeyAlias>
               <TrustStore>
                  ref://myCompanyTrustStoreRef
               </TrustStore>
            </SSLInfo>
         </HTTPTargetConnection>
         ...
      </TargetEndpoint>

   2. 上記の例では、TrustStore 参照名は myCompanyTruststoreRef です。

   3. Edge UI で、[Environments] > [References] を選択します。目的のトラストストア参照の [Reference] 列にある名前をメモします。これがトラストストアの名前になります。

      （ 大きい画像を表示）

      

   4. 上記の例では、トラストストア名は次のとおりです。

      myCompanyTruststoreRef: myCompanyTruststore

3. 次の API を使用して、前の手順で特定したトラストストアに保存されている証明書を取得します。

   1. キーストアまたはトラストストアの証明書をすべて取得します。この API により、特定のトラストストアの証明書の一覧が出力されます。

      パブリック クラウド ユーザー:

      curl -v -X GET https//api.enterprise.apigee.com/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs -H "Authorization: Bearer $TOKEN"
      

      Private Cloud ユーザー:

      curl -v -X GET http://MANAGEMENT_HOST:PORT_#/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs -H "Authorization: Bearer $TOKEN"
      

      ここで:

      • ORGANIZATION_NAME は組織の名前です
      • ENVIRONMENT_NAME は、環境の名前です。
      • KEYSTORE_NAME はキーストアの名前です
      • OAuth 2.0 アクセス トークンの取得の説明に従って、$TOKEN が OAuth 2.0 アクセス トークンに設定されている
      • この例で使用されている curl オプションについては、curl を使用するをご覧ください。

      出力例:

      サンプル トラストストア myCompanyTruststore の証明書は次のとおりです。

      [
        "serverCert"
      ]

   2. キーストアまたはトラストストアから特定の証明書の証明書の詳細を取得します。 この API は、特定のトラストストアにある特定の証明書に関する情報を返します。

      パブリック クラウド ユーザー:

      curl -v -X GET https//api.enterprise.apigee.com/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs/CERT_NAME -H "Authorization: Bearer $TOKEN"
      

      Private Cloud ユーザー

      curl -v -X GET http://MANAGEMENT_HOST:PORT_#>/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs/CERT_NAME -H "Authorization: Bearer $TOKEN"
      

      ここで:

      • ORGANIZATION_NAME は組織の名前です
      • ENVIRONMENT_NAME は、環境の名前です。
      • KEYSTORE_NAME はキーストアの名前です
      • CERT_NAME は証明書の名前です
      • OAuth 2.0 アクセス トークンの取得の説明に従って、$TOKEN が OAuth 2.0 アクセス トークンに設定されている
      • この例で使用されている curl オプションについては、curl を使用するをご覧ください。

      出力例:

      serverCert の詳細には、次のようにサブジェクトと発行者が表示されます。

      リーフ/エンティティ証明書:

      "subject": "CN=mocktarget.apigee.net",
      "issuer": "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",

      中間証明書:

      "subject" : "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      "issuer" : "CN=GTS Root R1, O=Google Trust Services LLC, C=US",

4. ステップ 1 で取得した実際のサーバー証明書と、ステップ 3 で取得したトラストストアに保存されている証明書が一致することを確認します。一致しない場合は、それが問題の原因です。

   上記の例から、証明書を 1 つずつ見ていきましょう。

   1. リーフ証明書:

      バックエンド サーバーから:

      s:/CN=mocktarget.apigee.net
      i:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4

      Message Processor（クライアント）のトラストストアから:

      "subject": "CN=mocktarget.apigee.net",
      "issuer": "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",

      トラストストアに格納されているリーフ証明書がバックエンド サーバーの証明書と一致している。

   2. 中間証明書:

      バックエンド サーバーから:

      s:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
      i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1

      Message Processor（クライアント）のトラストストアから:

      "subject" : "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      "issuer" : "CN=GTS Root R1, O=Google Trust Services LLC, C=US",

      トラストストアに保存されている中間証明書がバックエンド サーバーの証明書と一致している。

   3. ルート証明書:

      バックエンド サーバーから:

      s:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
      i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1

      ルート証明書が Message Processor のトラストストアにまったく存在しない。

   4. トラストストアにルート証明書がないため、Message Processor は次の例外をスローします。

      sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

      エラーコード messaging.adaptors.http.flow.SslHandshakeFailed を含む 503 Service Unavailable をクライアント アプリケーションに返します。

正しい FQDN

バックエンド サーバーのキーストアを正しい FQDN、有効で完全な証明書チェーンで更新します。

1. 正しい FQDN を持つバックエンド サーバーの証明書がない場合は、適切な CA（認証局）から適切な証明書を取得します。

2. 有効で完全なバックエンド サーバーの証明書チェーンがあることを確認します。

3. ターゲット エンドポイントで指定されたホスト名と同じ、バックエンド サーバーの正しい FQDN を含む有効で完全な証明書チェーンがリーフ証明書またはエンティティ証明書にある場合は、完全な証明書チェーンでバックエンドのキーストアを更新します。

バックエンド サーバーを修正する

正しいバックエンド サーバーのホスト名でターゲット エンドポイントを更新します。

1. ターゲット エンドポイントでホスト名が正しく指定されていない場合は、バックエンド サーバーの証明書の FQDN と一致する正しいホスト名になるようにターゲット エンドポイントを更新します。

2. API プロキシへの変更を保存します。

   上記の例で、バックエンド サーバーのホスト名が正しく指定されていない場合は、バックエンド サーバーの証明書の FQDN（backend.apigee.net）を使用して次のように修正できます。

   <TargetEndpoint name="default">
      …
      <HTTPTargetConnection>
         <Properties />
         <SSLInfo>
            <Enabled>true</Enabled>
            <TrustStore>ref://myTrustStoreRef</TrustStore>
         </SSLInfo>
         <URL>https://backend.apigee.net/resource</URL>
      </HTTPTargetConnection>
   </TargetEndpoint>