503 Service Unavailable - SSL handshake エラー

API Monitoring

手順 1: API Monitoring の使用

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

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

2. 問題を調査する組織に切り替えます。

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

5. [Time] に [Fault Code] をプロットします。

6. 次のように、障害コード messaging.adaptors.http.flow.SslHandshakeFailed を含むセルを選択します。

   （ 拡大画像を表示）

   

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

   （ 拡大画像を表示）

   

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

   （ 拡大画像を表示）

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

Trace

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

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

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

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

   
3. 失敗したリクエストの 1 つを選択し、トレースを調べます。
4. トレースのさまざまなフェーズを順に確認し、エラーが発生した場所を見つけます。

5. 通常、次に示すように、このエラーはターゲット リクエスト フローの開始フェーズの後に発生します。

   （ 拡大画像を表示）

   
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 handshake に失敗したことを示します。
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. messaging.adaptors.http.flow.SslHandshakeFailed の値と一致する X-Apigee-fault-code の 503 エラーが見つかった場合は、X-Apigee-fault-source の値を特定します。

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

   （ 拡大画像を表示）

   

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

   ヘッダー	値
   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>
     

   handshake の失敗の原因は次のとおりです。

   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. 次の手順で、Message Processor のトラストストアに保存されている証明書を確認します。

   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] を選択します。特定のトラストストア参照の [参照] 列の名前をメモします。これがトラストストア名になります。

      （ 拡大画像を表示）

      

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

      myCompanyTruststoreRef: myCompanyTruststore

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

   1. キーストアまたはトラストストアのすべての証明書を取得する。この API は、特定のトラストストア内のすべての証明書を一覧表示します。

      Public Cloud ユーザー:

      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 はキーストアの名前です。
      • $TOKEN は、OAuth 2.0 アクセス トークンの取得の説明に従って、OAuth 2.0 アクセス トークンに設定されます。
      • この例で使用している curl オプションについては、curl を使用するをご覧ください。

      出力例:

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

      [
        "serverCert"
      ]
      

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

      Public Cloud ユーザー:

      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 は証明書の名前です。
      • $TOKEN は、OAuth 2.0 アクセス トークンの取得の説明に従って、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
      

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

正しい 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>