Documentação do Oracle Cloud Infrastructure

Falha no handshake de TLS de backend HTTPS

Descubra como diagnosticar e solucionar problemas de falhas de handshake de TLS no backend HTTPS ao criar implantações de API com o serviço API Gateway.

Quando uma implantação de API usa um back-end HTTPS, uma falha de handshake TLS pode interromper a solicitação antes que o serviço de back-end processe qualquer tráfego HTTP. Em geral, a falha significa que o API Gateway não pode validar a cadeia de certificados ou a configuração TLS que o back-end apresenta.

Sintomas do Problema

Você pode ver um ou mais dos seguintes sintomas:

  • O URL de back-end está correto, mas a solicitação falha antes que o serviço de back-end processe a solicitação HTTP.

  • O log de execução mostra o código de log httpBackend.requestError.

  • A mensagem de log de execução termina com HANDSHAKE_FAILED.

  • As solicitações falham quando o serviço de back-end usa uma autoridade de certificação (CA) privada, um bundle de CAs personalizado ou uma cadeia de certificados em que o Gateway de API não confia.

Possíveis Causas

Falhas de handshake TLS no back-end HTTPS geralmente têm uma das seguintes causas:

  • O certificado de backend expirou, está incompleto ou é inválido.

  • A cadeia de certificados de back-end não tem um certificado intermediário.

  • A cadeia de certificados usa uma CA que não está no armazenamento confiável do Gateway de API.

  • O listener TLS de back-end está configurado incorretamente, incluindo definições TLS não suportadas ou incorretas.

  • A sessão TLS falha antes que o API Gateway possa enviar a solicitação HTTP para o back-end.

Revisar Mensagens de Log

Repita a solicitação por meio do Gateway de API e, em seguida, revise o log de execução da mesma solicitação.

Use o seguinte comando para repetir a solicitação:

  • curl -i https://<gateway-hostname>/<deployment-path-prefix>/<api-route-path>

No Logging, verifique os seguintes detalhes de log:

  • Capture o opc-request-id da solicitação com falha.

  • Abra o log de execução da mesma solicitação.

  • Confirme se o código de log é httpBackend.requestError.

  • Confirme se a mensagem termina com HANDSHAKE_FAILED.

A seguinte mensagem de log indica que o handshake TLS falhou antes que o gateway enviasse a solicitação HTTP para o back-end:

  • An error occurred whilst sending request to https://<backend-url>: HANDSHAKE_FAILED

Revisar a Configuração de Back-End HTTPS

Revise a rota e a configuração de back-end para a solicitação com falha.

  • Confirme se backend.url aponta para o back-end HTTPS esperado.

  • Confirme se o listener de back-end apresenta uma cadeia de certificados completa.

  • Se o back-end usar uma CA privada ou um bundle de CAs personalizado, confirme se o armazenamento confiável do gateway de API inclui o bundle de CAs ou a CA necessária.

  • Confirme se a configuração do listener TLS corresponde aos requisitos de back-end e armazenamento confiável HTTPS para a implantação de API.

Validar o Back-End HTTPS Diretamente

Em um sistema que pode acessar o back-end diretamente, teste o listener HTTPS fora do Gateway de API.

Use o seguinte comando para inspecionar o handshake TLS:

  • curl -v <backend-url>

Revise os resultados do teste direto para obter os seguintes detalhes:

  • A cadeia de certificados que o listener de back-end apresenta.

  • As datas de expiração do certificado e a cobertura do nome do host.

  • O protocolo TLS e a configuração de cifragem.

  • Qualquer erro de validação de certificado que ocorra antes do envio da solicitação HTTP.

Corrigir Problemas de TLS de Back-End HTTPS

Aplique a correção que corresponde ao problema encontrado.

  • Se o certificado back-end expirou, está incompleto ou é inválido, substitua ou corrija a cadeia de certificados.

  • Se a cadeia de certificados não tiver um certificado intermediário, configure o listener de back-end para apresentar a cadeia completa.

  • Se o back-end usar uma CA privada ou um bundle de CAs personalizado, adicione a CA ou o bundle de CAs necessário ao armazenamento confiável do gateway de API.

  • Se o listener de back-end usar definições TLS incorretas, atualize a configuração do listener e repita a solicitação.

  • Se o log de execução mostrar httpBackend.requestError com HANDSHAKE_FAILED, diagnostique e solucione problemas do listener HTTPS antes de alterar a configuração da rota do Gateway de API.

Verificar Conectividade de Back-End HTTPS

Depois de corrigir a configuração de TLS, verifique se a implantação de API pode atingir o back-end HTTPS.

  • Envie a mesma solicitação por meio do API Gateway.

  • Confirme se o log de execução não mostra mais httpBackend.requestError com HANDSHAKE_FAILED.

  • Confirme se o serviço de back-end recebe e processa a solicitação HTTP.

Para obter mais informações

Para obter mais informações, consulte: