503 Service indisponible – Échec de handshake SSL

Surveillance des API

Procédure 1 : Utiliser la surveillance des API

Pour diagnostiquer l'erreur à l'aide d'API Monitoring :

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

2. Basculez vers l'organisation dans laquelle vous souhaitez examiner le problème.

   
3. Accédez à la page Analyser > API Monitoring > Examiner.
4. Sélectionnez la période spécifique au cours de laquelle vous avez observé les erreurs.

5. Représentez graphiquement Code d'erreur par rapport à Heure.

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

   ( Agrandir l'image)

   

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

   ( Agrandir l'image)

   

8. Cliquez sur Afficher les journaux , puis développez la ligne correspondant à la demande ayant échoué.

   ( Agrandir l'image)

   
9. Dans la fenêtre Journaux, notez les informations suivantes :
   • ID du message de demande
   • Code d'état : 503
   • Source de la défaillance : 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 et l'une des options suivantes :
   • Attendez que l'erreur 503 Service Unavailable se produise avec le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed.
   • Si vous pouvez reproduire le problème, effectuez l'appel d'API pour le reproduire. 503 Service Unavailable

2. Assurez-vous que l'option Afficher toutes 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 identifiez l'emplacement de l'échec.

5. L'erreur se trouve généralement après la phase Target Request Flow Started (Flux de requête cible démarré), comme indiqué ci-dessous :

   ( Agrandir l'image)

   
6. Notez les valeurs suivantes à 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 de backend.
7. Accédez à la phase AX (données Analytics enregistrées) dans la trace, puis cliquez dessus.

8. Faites défiler la page jusqu'à la section En-têtes d'erreur liés aux 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 :

   ( Agrandir l'image)

   
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 3 : Utiliser les journaux d'accès NGINX

Pour diagnostiquer l'erreur à l'aide des journaux d'accès NGINX :

1. Si vous êtes un utilisateur Private Cloud, vous pouvez utiliser les journaux d'accès NGINX pour déterminer les informations clés sur 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 les éventuelles 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 dans le passé) ou s'il existe des requêtes qui é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 X-Apigee-fault-source.

   Exemple d'erreur 503 dans le journal d'accès NGINX :

   ( Agrandir l'image)

   

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

   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 d'API Monitoring, de l'outil Trace ou des journaux d'accès NGINX, comme expliqué dans É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 s'afficher :

   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 de backend.

   Une exception avec une trace de la pile détaillée s'affichera ensuite, 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 de l'établissement de la liaison est dû aux raisons suivantes :

   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 de backend.

Phase 1

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

Utilisez l'une des méthodes suivantes pour déterminer la chaîne de certificats du serveur de 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 : Comparez 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 de 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 truststore à partir de l'élément TrustStore dans la section SSLInfo du 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 Environnements > Références. Notez le nom dans la colonne Référence pour la référence spécifique du truststore. Il s'agit du nom de votre truststore.

      ( Agrandir l'image)

      

   4. Dans l'exemple ci-dessus, le nom du truststore est le suivant :

      myCompanyTruststoreRef : myCompanyTruststore

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

   1. Obtenez tous les certificats pour un keystore ou un truststore. Cette API liste tous les certificats du truststore 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 Utiliser curl.

      Exemple de résultat :

      Les certificats du truststore de l'exemple myCompanyTruststore sont les suivants :

      [
        "serverCert"
      ]

   2. Obtenez les détails d'un certificat spécifique à partir d'un Keystore ou d'un Truststore. Cette API renvoie des informations sur un certificat spécifique dans le truststore 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 du 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 Utiliser curl.

      Exemple de résultat

      Les détails de serverCert affichent le sujet et l'émetteur comme suit :

      Certificat de feuille/d'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 obtenu à l'étape 3 correspondent. Si elles ne correspondent pas, il s'agit de la cause du problème.

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

   1. Certificat feuille :

      Depuis le serveur de backend :

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

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

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

      Le certificat feuille stocké dans le truststore correspond à celui du serveur backend.

   2. Certificat intermédiaire :

      Depuis le serveur de 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 du processeur de messages (client) :

      "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 de backend.

   3. Certificat racine :

      Depuis le serveur de 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 totalement absent du 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 de backend avec le 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 de backend avec le nom de domaine complet approprié, procurez-vous le certificat approprié auprès d'une autorité de certification.

2. Vérifiez que vous disposez d'une chaîne de certificats de serveur backend 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 correct du serveur backend dans le certificat de feuille ou d'entité, qui est 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.

Corriger le serveur backend

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é spécifié de manière incorrecte dans le point de terminaison cible, mettez à jour le point de terminaison cible pour qu'il comporte le nom d'hôte correct correspondant au nom de domaine complet dans le certificat du serveur backend.

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

   Dans l'exemple ci-dessus, si le nom d'hôte du serveur backend a été spécifié de manière incorrecte, vous pouvez le corriger en utilisant le nom de domaine complet du certificat du serveur backend, c'est-à-dire 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>