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

Monitoramento de APIs

Procedimento 1: usar o API Monitoring

Para diagnosticar o erro usando o API Monitoring:

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

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

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

5. Crie um gráfico com Código de falha e Tempo.

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

   ( ampliar imagem)

   

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

   ( ampliar imagem)

   

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

   ( ampliar imagem)

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

Trace

Procedimento 2: usar a ferramenta Trace

Para diagnosticar o erro usando a ferramenta Trace:

1. Ative a sessão de rastreamento e uma das seguintes opções:
   • Aguarde o erro 503 Service Unavailable com o código messaging.adaptors.http.flow.SslHandshakeFailed ou
   • Se for possível reproduzir o problema, faça a chamada de API para reproduzir o problema 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 rastreamento.
4. Navegue pelas diferentes fases do rastreamento e localize onde a falha ocorreu.

5. Normalmente, você encontra o erro depois da fase Fluxo de solicitação de destino iniciado, conforme mostrado abaixo:

   ( ampliar imagem)

   
6. Observe os valores a seguir no rastreamento:
   • 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 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 a tela para baixo até a seção Cabeçalhos de erro de detalhes da fase e determine os valores de X-Apigee-fault-code, X-Apigee-fault-source e X-Apigee-Message-ID, conforme mostrado abaixo:

   ( ampliar imagem)

   
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 3: usar registros de acesso do NGINX

Para diagnosticar o erro usando registros de acesso do NGINX:

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

2. Verifique os registros de acesso do NGINX:

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

3. Pesquise para ver se há erros de 503 com o código de erro messaging.adaptors.http.flow.SslHandshakeFailed durante um período específico (se o problema aconteceu no passado) ou se ainda há solicitações com falha em 503.

4. Se você encontrar erros de 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:

   ( ampliar imagem)

   

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

   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 registros do processador de mensagens

1. Determine o ID da mensagem de uma das solicitações com falha usando o API Monitoring, a ferramenta Trace ou os registros de acesso do NGINX, conforme explicado em Etapas comuns de diagnóstico.

2. Procure 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). Talvez você veja o seguinte erro:

   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 rastreamento de pilha 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 no handshake ocorreu devido a:

   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 seguintes métodos 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 o certificado do servidor de back-end e os certificados armazenados no repositório de confiança do processador de mensagens

1. Determine a cadeia de certificados do servidor de back-end.
2. Determine o certificado armazenado no truststore do processador de mensagens usando as seguintes etapas:

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

      Confira um exemplo de seção SSLInfo em uma configuração 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 usuário do Edge, selecione Ambientes > Referências. Observe o nome na coluna Referência para a referência específica do keystore de confiança. Esse será o nome do seu truststore.

      ( ampliar imagem)

      

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

      myCompanyTruststoreRef: myCompanyTruststore

3. Receba 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 do OAuth 2.0, conforme descrito em Receber um token de acesso do OAuth 2.0
      • As opções de curl usadas neste exemplo estão descritas em Usar curl

      Exemplo de resposta:

      Os certificados do exemplo de keystore de confiança myCompanyTruststore são:

      [
        "serverCert"
      ]

   2. Receba os detalhes de um certificado específico de um armazenamento de chaves ou de confiança. Essa API retorna informações sobre um certificado específico no keystore de confiança 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 do OAuth 2.0, conforme descrito em Receber um token de acesso do 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 forma:

      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 do servidor real obtido na etapa 1 e o certificado armazenado no repositório de confiança obtido na etapa 3 correspondem. Se não corresponderem, essa é a causa do problema.

   No exemplo acima, vamos analisar um certificado por vez:

   1. Certificado folha:

      No servidor de back-end:

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

      Do repositório de confiança do processador de mensagens (cliente):

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

      O certificado 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

      Do repositório de confiança 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 repositório de confiança 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 uma cadeia de certificados válida e completa:

1. Se você não tiver um certificado de servidor de back-end com o FQDN correto, consiga o certificado adequado de uma AC (autoridade certificadora) apropriada.

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

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 do host correto do servidor de back-end:

1. Se o nome do host foi especificado incorretamente no endpoint de destino, atualize o endpoint de destino para ter o nome de host correto que corresponde ao FQDN no certificado do servidor de back-end.

2. Salve as mudanças no proxy de API.

   No exemplo acima, se o nome do host do servidor de back-end foi especificado incorretamente, use o FQDN do certificado do servidor de back-end, ou seja, 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>