503 Serviço indisponível - Falha no handshake de SSL

Monitoramento de APIs

Procedimento 1: usar o monitoramento de APIs

Para diagnosticar o erro usando o monitoramento de APIs:

1. Faça login na interface do Apigee Edge como usuário com um papel apropriado.

2. Alterne para a organização em que você quer investigar o problema.

   
3. Navegue até a página Analisar > Monitoramento de API > Investigar.
4. Selecione o período específico em que você observou os erros.

5. Trace o Código de falha em relação a Time.

6. Selecione uma célula que tenha o código de falha messaging.adaptors.http.flow.SslHandshakeFailed, conforme mostrado abaixo:

   ( ver imagem ampliada)

   

7. As informações sobre o código de falha messaging.adaptors.http.flow.SslHandshakeFailed são mostradas conforme mostrado abaixo:

   ( ver imagem ampliada)

   

8. Clique em Ver registros e expanda a linha da solicitação com falha.

   ( ver imagem ampliada)

   
9. Na janela Registros, observe os seguintes detalhes:
   • Solicitar ID da mensagem
   • Código de status: 503
   • Origem da falha: target
   • Código de falha: messaging.adaptors.http.flow.SslHandshakeFailed

Trace

Procedimento 2: uso da ferramenta Trace

Para diagnosticar o erro usando a ferramenta Trace:

1. Ative a sessão de rastreamento e:
   • Aguarde a ocorrência do erro 503 Service Unavailable com o código de erro messaging.adaptors.http.flow.SslHandshakeFailed ou
   • Se for possível reproduzir o problema, faça a chamada de API para reproduzi-lo 503 Service Unavailable

2. Verifique se a opção Mostrar todos os FlowInfos está ativada:

   
3. Selecione uma das solicitações com falha e examine o rastro.
4. Navegue pelas diferentes fases do rastro e localize onde a falha ocorreu.

5. O erro geralmente ocorre após o início da fase Target Request Flow, conforme mostrado abaixo:

   ( ver imagem ampliada)

   
6. Observe os valores a seguir no rastro:
   • erro: 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
   • O valor do erro 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 indica que o handshake de SSL falhou, porque o processador de mensagens do Apigee Edge não conseguiu validar o certificado do servidor de back-end.
7. Navegue até a fase AX (Dados do Analytics registrados) no rastreamento e clique nela.

8. Role para baixo até a seção Stage Details Error Headers e determine os valores de X-Apigee-fault-code, X-Apigee-fault-source e X-Apigee-Message-ID, conforme mostrado abaixo:

   ( ver imagem ampliada)

   
9. Observe os valores de X-Apigee-fault-code, X-Apigee-fault-source e X-Apigee-Message-ID:

Cabeçalhos de erro	Valor
X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
X-Apigee-fault-source	target
X-Apigee-Message-ID	MESSAGE_ID

NGINX

Procedimento no 3: uso de registros de acesso do NGINX

Para diagnosticar o erro usando os registros de acesso do NGINX:

1. Se você for um usuário de nuvem privada, poderá usar os registros de acesso do NGINX para determinar as principais informações sobre o HTTP 503 Service Unavailable.

2. Verifique os registros de acesso do NGINX:

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

3. Pesquise se há algum erro 503 com o código messaging.adaptors.http.flow.SslHandshakeFailed durante um período específico (se o problema tiver acontecido anteriormente) ou se ainda há alguma solicitação com falha com 503.

4. Se você encontrar erros 503 com o X-Apigee-fault-code correspondente ao valor de messaging.adaptors.http.flow.SslHandshakeFailed, determine o valor de X-Apigee-fault-source.

   Exemplo de erro 503 do registro de acesso do NGINX:

   ( ver imagem ampliada)

   

   A entrada de amostra acima do registro de acesso do NGINX tem os seguintes valores para X-Apigee-fault-code e X-Apigee-fault-code :

   Cabeçalhos	Valor
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

Registros do processador de mensagens

Procedimento 4: usar os registros do processador de mensagens

1. Determine o código da mensagem de uma das solicitações com falha usando o monitoramento de APIs, a ferramenta de rastreamento ou os registros de acesso do NGINX, conforme explicado nas Etapas comuns de diagnóstico.

2. Pesquise o ID da mensagem de solicitação específica no registro do processador de mensagens (/opt/apigee/var/log/edge-message-processor/logs/system.log). O seguinte erro poderá aparecer:

   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
   

   O erro acima indica que o handshake de SSL falhou entre o processador de mensagens e o servidor de back-end.

   Isso será seguido por uma exceção com stack trace detalhado, conforme mostrado abaixo:

   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>
     

   A falha de handshake ocorre pelos seguintes motivos:

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

   Isso indica que o handshake de SSL falhou porque o processador de mensagens do Apigee Edge não conseguiu validar o certificado do servidor de back-end.

Fase 1

Fase 1: determinar a cadeia de certificados do servidor de back-end

Use um dos métodos a seguir para determinar a cadeia de certificados do servidor de back-end:

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

Fase 2

Fase 2: comparar os certificados e os certificados do servidor de back-end armazenados no truststore do processador de mensagens

1. Determine a cadeia de certificados do servidor de back-end.
2. Para determinar o certificado armazenado no truststore do processador de mensagens, siga estas etapas:

   1. Consiga o nome de referência do truststore do elemento TrustStore na seção SSLInfo do TargetEndpoint.

      Veja um exemplo de seção SSLInfo em uma configuração de 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. No exemplo acima, o nome de referência TrustStore é myCompanyTruststoreRef.

   3. Na interface do Edge, selecione Ambientes > Referências. Observe o nome na coluna Reference da referência específica do truststore. Esse será o nome do seu truststore.

      ( ver imagem ampliada)

      

   4. No exemplo acima, o nome do truststore é:

      myCompanyTruststoreRef: myCompanyTruststore

3. Consiga os certificados armazenados no truststore (determinado na etapa anterior) usando as seguintes APIs:

   1. Receba todos os certificados de um keystore ou truststore. Essa API lista todos os certificados no truststore específico.

      Usuário da nuvem pública:

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

      Usuário da nuvem privada:

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

      Onde:

      • ORGANIZATION_NAME é o nome da organização.
      • ENVIRONMENT_NAME é o nome do ambiente;
      • KEYSTORE_NAME é o nome do keystore.
      • $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Receber um token de acesso OAuth 2.0.
      • As opções de curl usadas neste exemplo estão descritas em Usar curl

      Exemplo de resposta:

      Os certificados do truststore de exemplo myCompanyTruststore são:

      [
        "serverCert"
      ]
      

   2. Confira os detalhes do certificado específico de um keystore ou de um Truststore. Essa API retorna as informações sobre um certificado específico no truststore específico.

      Usuário da nuvem pública:

      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"
      

      Usuário da nuvem privada

      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"
      

      Onde:

      • ORGANIZATION_NAME é o nome da organização.
      • ENVIRONMENT_NAME é o nome do ambiente;
      • KEYSTORE_NAME é o nome do keystore.
      • CERT_NAME é o nome do certificado.
      • $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Receber um token de acesso OAuth 2.0.
      • As opções de curl usadas neste exemplo estão descritas em Usar curl

      Exemplo de saída

      Os detalhes de serverCert mostram o assunto e o emissor da seguinte maneira:

      Certificado de folha/entidade:

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

      Certificado intermediário:

      "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. Verifique se o certificado real do servidor recebido na etapa 1 e o certificado armazenado no truststore obtido na etapa 3 correspondem. Se eles não corresponderem, essa é a causa do problema.

   No exemplo acima, vamos analisar um certificado de cada vez:

   1. Certificado de folha:

      No servidor de back-end:

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

      No truststore do processador de mensagens (cliente):

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

      O certificado de folha armazenado no truststore corresponde ao do servidor de back-end.

   2. Certificado intermediário:

      No servidor de back-end:

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

      No truststore do processador de mensagens (cliente):

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

      O certificado intermediário armazenado no truststore corresponde ao do servidor de back-end.

   3. Certificado raiz:

      No servidor de back-end:

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

      O certificado raiz está completamente ausente no truststore do processador de mensagens.

   4. Como o certificado raiz está ausente no truststore, o processador de mensagens gera a seguinte exceção:

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

      e retorna 503 Service Unavailable com o código de erro messaging.adaptors.http.flow.SslHandshakeFailed para os aplicativos clientes.

FQDN correto

Atualize o keystore do servidor de back-end com o FQDN correto e a cadeia de certificados completa e válida:

1. Se você não tiver o certificado do servidor de back-end com o FQDN correto, consiga o certificado adequado de uma CA (autoridade de certificação) apropriada.

2. Verifique se você tem uma cadeia de certificados do servidor de back-end válida e completa.

3. Depois de ter a cadeia de certificados válida e completa com o FQDN correto do servidor de back-end no certificado de folha ou de entidade idêntico ao nome do host especificado no endpoint de destino, atualize o keystore do back-end com a cadeia de certificados completa.

Servidor de back-end correto

Atualize o endpoint de destino com o nome de host do servidor de back-end correto:

1. Se o nome do host tiver sido especificado incorretamente no endpoint de destino, atualize-o para que tenha o nome de host correto que corresponda ao FQDN no certificado do servidor de back-end.

2. Salve as alterações feitas no proxy de API.

   No exemplo discutido acima, se o nome do host do servidor de back-end foi especificado incorretamente, é possível corrigi-lo usando o FQDN do certificado do servidor de back-end, que é backend.apigee.net da seguinte maneira:

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