Documentazione dell'infrastruttura Oracle Cloud

Handshake TLS backend HTTPS non riuscito

Scopri come risolvere i problemi degli errori di handshake TLS backend HTTPS durante la creazione delle distribuzioni API con il servizio Gateway API.

Quando una distribuzione API utilizza un backend HTTPS, un errore di handshake TLS può arrestare la richiesta prima che il servizio backend elabori qualsiasi traffico HTTP. In genere, l'errore indica che API Gateway non è in grado di convalidare la catena di certificati o la configurazione TLS presentata dal backend.

Sintomi problema

Potresti vedere uno o più dei seguenti sintomi:

  • L'URL backend è corretto, ma la richiesta non riesce prima che il servizio backend elabori la richiesta HTTP.

  • Il log di esecuzione mostra il codice di log httpBackend.requestError.

  • Il messaggio execution-log termina con HANDSHAKE_FAILED.

  • Le richieste non riescono quando il servizio backend utilizza un'autorità di certificazione privata (CA), un bundle CA personalizzato o una catena di certificati non considerati attendibili dal gateway API.

Cause possibili

Gli errori di handshake TLS backend HTTPS in genere hanno una delle seguenti cause:

  • Il certificato backend è scaduto, è incompleto o non è valido.

  • Nella catena di certificati backend manca un certificato intermedio.

  • La catena di certificati utilizza una CA che non si trova nel truststore del gateway API.

  • Il listener TLS backend non è configurato correttamente, incluse le impostazioni TLS non supportate o errate.

  • La sessione TLS non riesce prima che il gateway API possa inviare la richiesta HTTP al backend.

Rivedi messaggi di log

Ripetere la richiesta tramite API Gateway, quindi rivedere il log di esecuzione per la stessa richiesta.

Utilizzare il comando seguente per ripetere la richiesta:

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

In Log, controllare i dettagli di log riportati di seguito.

  • Acquisire opc-request-id per la richiesta non riuscita.

  • Aprire il log di esecuzione per la stessa richiesta.

  • Verificare se il codice di log è httpBackend.requestError.

  • Confermare se il messaggio termina con HANDSHAKE_FAILED.

Il seguente messaggio di log indica che l'handshake TLS non è riuscito prima che il gateway inviasse la richiesta HTTP al backend:

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

Analisi della configurazione backend HTTPS

Rivedere l'instradamento e la configurazione backend per la richiesta non riuscita.

  • Verificare che backend.url punti al backend HTTPS previsto.

  • Verificare che il listener backend presenti una catena di certificati completa.

  • Se il backend utilizza un bundle CA privato o un bundle CA personalizzato, confermare che il truststore del gateway API include il bundle CA o CA richiesto.

  • Verificare che la configurazione del listener TLS corrisponda ai requisiti di back-end e trust-store HTTPS per la distribuzione dell'API.

Convalida direttamente il backend HTTPS

Da un sistema in grado di raggiungere direttamente il backend, eseguire il test del listener HTTPS al di fuori del gateway API.

Per esaminare l'handshake TLS, utilizzare il comando seguente:

  • curl -v <backend-url>

Esaminare i risultati dei test diretti per i dettagli riportati di seguito.

  • Catena di certificati presentata dal listener backend.

  • Le date di scadenza del certificato e la copertura del nome host.

  • Il protocollo TLS e la configurazione di cifratura.

  • Qualsiasi errore di convalida del certificato che si verifica prima dell'invio della richiesta HTTP.

Correggi problemi TLS back-end HTTPS

Applicare la correzione corrispondente al problema trovato.

  • Se il certificato backend è scaduto, è incompleto o non è valido, sostituire o correggere la catena di certificati.

  • Se alla catena di certificati manca un certificato intermedio, configurare il listener backend per presentare l'intera catena.

  • Se il backend utilizza un bundle CA privato o CA personalizzato, aggiungere il bundle CA o CA richiesto al truststore del gateway API.

  • Se il listener backend utilizza impostazioni TLS errate, aggiornare la configurazione del listener e riprovare la richiesta.

  • Se il log di esecuzione mostra httpBackend.requestError con HANDSHAKE_FAILED, risolvere i problemi del listener HTTPS prima di modificare la configurazione di instradamento del gateway API.

Verifica connettività backend HTTPS

Dopo aver corretto la configurazione TLS, verificare che la distribuzione dell'API possa raggiungere il backend HTTPS.

  • Invia la stessa richiesta tramite API Gateway.

  • Verificare che il log di esecuzione non mostri più httpBackend.requestError con HANDSHAKE_FAILED.

  • Confermare che il servizio backend riceve ed elabora la richiesta HTTP.

Per ulteriori informazioni

Per ulteriori informazioni, fare riferimento agli argomenti sotto riportati.