503 Service indisponible – Échec de handshake SSL

Surveillance des API

Procédure 1: Utiliser la surveillance des API

Pour diagnostiquer l'erreur à l'aide de la surveillance des API:

1. Connectez-vous à l'interface utilisateur Apigee Edge en tant qu'utilisateur disposant du rôle approprié.

2. Accédez à l'organisation dans laquelle vous souhaitez examiner le problème.

   
3. Accédez à la page Analyze > API Monitoring > Investigate (Analyser > Surveillance des API > Enquêter).
4. Sélectionnez la période spécifique au cours de laquelle vous avez observé les erreurs.

5. Tracez le code d'erreur par rapport à l'heure.

6. Sélectionnez une cellule contenant le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed, comme indiqué ci-dessous:

   ( Afficher l'image plus grande)

   

7. Les informations sur le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed s'affichent comme indiqué ci-dessous:

   ( Afficher l'image plus grande)

   

8. Cliquez sur Afficher les journaux , puis développez la ligne de la requête ayant échoué.

   ( Afficher l'image plus grande)

   
9. Dans la fenêtre Journaux, notez les détails suivants :
   • ID du message de requête
   • Code d'état:503
   • Source de l'erreur: target
   • Code d'erreur:messaging.adaptors.http.flow.SslHandshakeFailed

Trace

Procédure 2: Utiliser l'outil Trace

Pour diagnostiquer l'erreur à l'aide de l'outil Trace:

1. Activez la session de trace, puis effectuez l'une des opérations suivantes :
   • Attendez que l'erreur 503 Service Unavailable avec le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed se produise, ou
   • Si vous pouvez reproduire le problème, effectuez l'appel d'API pour le reproduire. 503 Service Unavailable

2. Assurez-vous que l'option Show all FlowInfos (Afficher tous les FlowInfos) est activée:

   
3. Sélectionnez l'une des requêtes ayant échoué et examinez la trace.
4. Parcourez les différentes phases de la trace et localisez l'origine de l'échec.

5. L'erreur se produit généralement après la phase Début du flux de requête cible, comme indiqué ci-dessous:

   ( Afficher l'image plus grande)

   
6. Notez les valeurs des éléments suivants à partir de la trace :
   • erreur: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
   • La valeur de l'erreur 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 indique que le handshake SSL a échoué, car le processeur de messages d'Apigee Edge n'a pas pu valider le certificat du serveur backend.
7. Accédez à la phase AX (Données analytiques enregistrées) dans la trace et cliquez dessus.

8. Faites défiler la page jusqu'à la section En-têtes d'erreur des détails de la phase et déterminez les valeurs de X-Apigee-fault-code, X-Apigee-fault-source et X-Apigee-Message-ID, comme indiqué ci-dessous:

   ( Afficher l'image plus grande)

   
9. Notez les valeurs de X-Apigee-fault-code, X-Apigee-fault-source et X-Apigee-Message-ID:

En-têtes d'erreur	Valeur
X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
X-Apigee-fault-source	target
X-Apigee-Message-ID	MESSAGE_ID

NGINX

Procédure n° 3: Utiliser les journaux d'accès NGINX

Pour diagnostiquer l'erreur à l'aide des journaux d'accès NGINX, procédez comme suit:

1. Si vous êtes un utilisateur du cloud privé, vous pouvez utiliser les journaux d'accès NGINX pour déterminer les informations clés concernant HTTP 503 Service Unavailable.

2. Vérifiez les journaux d'accès NGINX:

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

3. Recherchez s'il existe des erreurs 503 avec le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed pendant une durée spécifique (si le problème s'est produit par le passé) ou si des requêtes échouent toujours avec 503.

4. Si vous trouvez des erreurs 503 avec le X-Apigee-fault-code correspondant à la valeur de messaging.adaptors.http.flow.SslHandshakeFailed, déterminez la valeur de la X-Apigee-fault-source.

   Exemple d'erreur 503 du journal d'accès NGINX:

   ( Afficher l'image plus grande)

   

   L'exemple d'entrée ci-dessus du journal d'accès NGINX contient les valeurs suivantes pour X-Apigee-fault-code et X-Apigee-fault-code :

   En-têtes	Valeur
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

Journaux du processeur de messages

Procédure 4: Utiliser les journaux du processeur de messages

1. Déterminez l'ID de message de l'une des requêtes ayant échoué à l'aide de l'API Monitoring, de l'outil Trace ou des journaux d'accès NGINX, comme expliqué dans la section Étapes de diagnostic courantes.

2. Recherchez l'ID du message de requête spécifique dans le journal du processeur de messages (/opt/apigee/var/log/edge-message-processor/logs/system.log). L'erreur suivante peut se produire:

   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
   

   L'erreur ci-dessus indique que le handshake SSL a échoué entre le processeur de messages et le serveur backend.

   Cette étape est suivie d'une exception avec une trace de pile détaillée, comme indiqué ci-dessous:

   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>
     

   Notez que l'échec du handshake est dû aux éléments suivants:

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

   Cela indique que le handshake SSL a échoué, car le processeur de messages d'Apigee Edge n'a pas pu valider le certificat du serveur backend.

Phase 1

Phase 1: Déterminer la chaîne de certificats du serveur backend

Utilisez l'une des méthodes suivantes pour déterminer la chaîne de certificats du serveur backend:

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

Phase 2

Phase 2: Comparer le certificat du serveur backend et les certificats stockés dans le Truststore du processeur de messages

1. Déterminez la chaîne de certificats du serveur backend.
2. Déterminez le certificat stocké dans le Truststore du processeur de messages en procédant comme suit :

   1. Obtenez le nom de référence du magasin de confiance à partir de l'élément TrustStore de la section SSLInfo du fichier TargetEndpoint.

      Examinons un exemple de section SSLInfo dans une configuration TargetEndpoint:

      <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. Dans l'exemple ci-dessus, le nom de référence TrustStore est myCompanyTruststoreRef.

   3. Dans l'interface utilisateur Edge, sélectionnez Environments > References (Environnements > Références). Notez le nom dans la colonne Reference (Référence) pour la référence du truststore spécifique. Il s'agira du nom de votre Trustedstore.

      ( Afficher l'image plus grande)

      

   4. Dans l'exemple ci-dessus, le nom du magasin de confiance est:

      myCompanyTruststoreRef: myCompanyTruststore

3. Récupérez les certificats stockés dans le Truststore (déterminé à l'étape précédente) à l'aide des API suivantes:

   1. Obtenez tous les certificats d'un keystore ou d'un magasin de confiance. Cette API liste tous les certificats du magasin de confiance spécifique.

      Utilisateur du cloud public:

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

      Utilisateur 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"
      

      Où:

      • ORGANIZATION_NAME est le nom de l'organisation.
      • ENVIRONMENT_NAME est le nom de l'environnement.
      • KEYSTORE_NAME est le nom du keystore.
      • $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0.
      • Les options curl utilisées dans cet exemple sont décrites dans la section Utiliser curl.

      Exemple de résultat :

      Les certificats de l'exemple de magasin de confiance myCompanyTruststore sont les suivants :

      [
        "serverCert"
      ]
      

   2. Obtenez les détails du certificat spécifique à partir d'un keystore ou d'un Truststore. Cette API renvoie les informations sur un certificat spécifique contenu dans le magasin de confiance spécifique.

      Utilisateur du cloud public:

      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"
      

      Utilisateur 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"
      

      Où:

      • ORGANIZATION_NAME est le nom de l'organisation.
      • ENVIRONMENT_NAME est le nom de l'environnement.
      • KEYSTORE_NAME est le nom du keystore.
      • CERT_NAME est le nom du certificat.
      • $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0.
      • Les options curl utilisées dans cet exemple sont décrites dans la section Utiliser curl.

      Exemple de résultat

      Les informations de serverCert indiquent l'objet et l'émetteur comme suit:

      Certificat de la feuille/entité:

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

      Certificat intermédiaire:

      "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. Vérifiez que le certificat de serveur réel obtenu à l'étape 1 et le certificat stocké dans le Truststore obtenus à l'étape 3 correspondent. Si ce n'est pas le cas, c'est la cause du problème.

   Dans l'exemple ci-dessus, examinons un certificat à la fois:

   1. Certificat de la feuille:

      Depuis le serveur backend:

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

      À partir du Truststore (client) du processeur de messages:

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

      Le certificat d'entité finale stocké dans le Truststore correspond à celui du serveur backend.

   2. Certificat intermédiaire:

      Depuis le serveur backend:

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

      À partir du Truststore (client) du processeur de messages:

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

      Le certificat intermédiaire stocké dans le Truststore correspond à celui du serveur backend.

   3. Certificat racine:

      Depuis le serveur backend:

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

      Le certificat racine est complètement manquant dans le Truststore du processeur de messages.

   4. Étant donné que le certificat racine est manquant dans le truststore, le processeur de messages génère l'exception suivante:

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

      et renvoie 503 Service Unavailable avec le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed aux applications clientes.

Nom de domaine complet correct

Mettez à jour le keystore du serveur backend avec un nom de domaine complet correct, ainsi qu'une chaîne de certificats valide et complète:

1. Si vous ne disposez pas d'un certificat de serveur backend avec le nom de domaine complet approprié, procurez-vous le certificat approprié auprès d'une autorité de certification (autorité de certification) appropriée.

2. Vérifiez que la chaîne de certificats du serveur backend est valide et complète.

3. Une fois que vous disposez de la chaîne de certificats valide et complète, avec le nom de domaine complet du serveur backend (dans le certificat d'entité finale ou le certificat d'entité) identique au nom d'hôte spécifié dans le point de terminaison cible, mettez à jour le keystore du backend avec la chaîne de certificats complète.

Serveur backend approprié

Mettez à jour le point de terminaison cible avec le nom d'hôte du serveur backend approprié:

1. Si le nom d'hôte a été incorrectement spécifié dans le point de terminaison cible, mettez-le à jour afin qu'il corresponde au nom d'hôte correspondant au nom de domaine complet du certificat du serveur backend.

2. Enregistrez les modifications apportées au proxy d'API.

   Dans l'exemple décrit ci-dessus, si le nom d'hôte du serveur backend n'a pas été spécifié correctement, vous pouvez le corriger en utilisant le nom de domaine complet du certificat du serveur backend, soit backend.apigee.net, comme suit:

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