503 Service indisponible – Échec de handshake SSL

Surveillance des API

Procédure n° 1: Utiliser la surveillance des API

Pour diagnostiquer l'erreur à l'aide de l'API Monitoring, procédez comme suit:

1. <ph type="x-smartling-placeholder"></ph> Connectez-vous à l'interface utilisateur d'Apigee Edge en tant qu'utilisateur disposant d'un rôle approprié.

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

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

5. Représentez le code d'erreur par rapport à l'heure.

   <ph type="x-smartling-placeholder">

6. Sélectionnez une cellule contenant le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed tel qu'illustré ci-dessous:

   ( Agrandir l'image)

   

7. Informations sur le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed s'affiche sous la forme comme indiqué ci-dessous:

   ( Agrandir l'image)

   

8. Cliquez sur Afficher les journaux et développez la ligne correspondant à la requête ayant échoué.

   ( Agrandir l'image)

   
9. Dans la fenêtre Journaux, notez les détails suivants: <ph type="x-smartling-placeholder">
   </ph>
   • Demander un ID de message
   • Code d'état:503
   • Source de l'erreur:target
   • Code d'erreur: messaging.adaptors.http.flow.SslHandshakeFailed

Trace

Procédure n° 2: Utiliser l'outil Trace

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

1. Activez la session de trace, puis <ph type="x-smartling-placeholder">
   </ph>
   • Attendez l'erreur 503 Service Unavailable avec le code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed ne doit pas avoir lieu, 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 toutes les infos 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 s'affiche 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: <ph type="x-smartling-placeholder">
   </ph>
   • 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 la connexion certificat.
7. Accédez à la phase AX (Données analytiques enregistrées) dans la trace, puis cliquez dessus.

8. Faites défiler la page jusqu'à la section Phase Details Error Headers (En-têtes d'erreur des détails de la phase) et déterminez les valeurs de X-Apigee-fault-code et 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 n° 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 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

   <ph type="x-smartling-placeholder">
3. Effectuez une recherche pour voir s'il existe des erreurs 503 avec un code d'erreur messaging.adaptors.http.flow.SslHandshakeFailed pendant une durée spécifique (si le problème est survenu pendant ou si des requêtes échouent toujours avec 503.

4. Si vous trouvez des erreurs 503 avec la correspondance X-Apigee-fault-code la valeur de messaging.adaptors.http.flow.SslHandshakeFailed, puis déterminer 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 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 de processeur de messages

Procédure n° 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 la surveillance des API, de l'outil Trace ou NGINX Access Logs, comme expliqué dans la section Étapes de diagnostic courantes.

2. Rechercher 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). Vous pouvez observer l'erreur suivante:

   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 la négociation SSL a échoué entre le processeur de messages et le serveur backend.

   Cette action 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 imputable 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 était impossible de 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: Comparez le certificat du serveur backend avec les certificats stockés dans le Magasin de confiance 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 utilisant procédez comme suit: <ph type="x-smartling-placeholder">
   </ph>

   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 TargetEndpoint. configuration:

      <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 Colonne Référence pour la référence du truststore spécifique. Ce sera votre « Truststore ».

      ( Agrandir l'image)

      

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

      myCompanyTruststoreRef: myCompanyTruststore

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

   1. <ph type="x-smartling-placeholder"></ph> Obtenez tous les certificats d'un keystore ou d'un truststore. Cette API répertorie l'ensemble des dans le truststore concerné.

      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 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 de l'exemple de magasin de confiance myCompanyTruststore sont les suivants:

      [
        "serverCert"
      ]
      

   2. <ph type="x-smartling-placeholder"></ph> Obtenez les détails du certificat spécifique à partir d'un keystore ou d'un Truststore. Cette API renvoie les informations relatives à un certificat spécifique dans le Truststore.

      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 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 indiquent l'objet et l'émetteur comme suit:

      Certificat 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 du serveur réel obtenu à l'étape 1 et le certificat stocké dans le truststore obtenu à l'étape 3. Si ce n'est pas le cas, la cause du problème.

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

   1. Certificat 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 feuille stocké dans le truststore correspond à celui du backend. Google Cloud.

   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 à votre 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 absent du certificat Truststore.

   4. Comme le certificat racine est manquant dans le truststore, le 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 au client applications.

Nom de domaine complet correct

Mettez à jour le keystore du serveur backend avec le nom de domaine complet correct ainsi que le certificat valide et complet. chaîne:

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

2. Vérifiez que vous disposez d'une chaîne de certificats valide et complète.

   <ph type="x-smartling-placeholder">
3. Une fois que vous disposez d'une chaîne de certificats valide et complète avec le nom de domaine complet correct du serveur backend dans le certificat d'entité finale 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 complète de la chaîne de certificats.

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 n'a pas été correctement spécifié dans le point de terminaison cible, mettez à jour le que le nom d'hôte du point de terminaison cible corresponde au nom de domaine complet du backend certificat du serveur.

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

   Dans l'exemple mentionné ci-dessus, si le nom d'hôte du serveur backend était incorrect vous pouvez le résoudre en utilisant le nom de domaine complet du certificat du serveur backend, qui est 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>