Opzioni per la configurazione di TLS

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa sezione mostra come configurare TLS per il traffico da un proxy a una destinazione.

Versioni TLS non supportate:Apigee non supporta l'utilizzo di TLS 1.0 o TLS 1.1. Se utilizzi questi protocolli nella configurazione dell'endpoint di destinazione, l'endpoint di destinazione Apigee genera l'errore messaging.adaptors.http.flow.SslHandshakeFailed.

Informazioni sull'impostazione delle opzioni TLS in un endpoint di destinazione o in un server di destinazione

Un target può essere rappresentato da un oggetto XML come quello riportato di seguito:

<HTTPTargetConnection>
    <Properties/>
    <URL>https:myTargetAddress</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <Enforce>true</Enforce>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTruststoreRef</TrustStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <Protocols>myProtocols</Protocols>
        <Ciphers>myCipher</Ciphers>
    </SSLInfo>
</HTTPTargetConnection>

L'area della configurazione dell'endpoint di destinazione che modifichi per configurare TLS è definita dal tag <SSLInfo>. Utilizzi lo stesso tag <SSLInfo> per configurare un endpoint di destinazione o un server di destinazione.

Per informazioni sugli elementi secondari di <SSLInfo>, consulta Configurazione di TargetEndpoint TLS/SSL.

La tabella seguente descrive gli elementi di configurazione TLS utilizzati dal tag <SSLInfo>:

Elemento	Descrizione
<Enabled>	Il blocco <SSLInfo> può essere utilizzato sia per TLS/SSL unidirezionale che bidirezionale. Se impostato su true, <Enabled> specifica che deve essere utilizzato il blocco <SSLInfo>. Se impostato su false, il blocco <SSLInfo> viene ignorato. Il valore predefinito di <Enabled> è true se <URL> specifica il protocollo HTTPS, e false se <URL> specifica HTTP.
<Enforce>	Applica SSL rigoroso tra Apigee e il backend di destinazione. Se impostato su true, le connessioni non andranno a buon fine per le destinazioni con certificati non validi, scaduti, autofirmati, con nome host non corrispondente e con una radice non attendibile. Viene restituito un codice di errore 4xx o 5xx. Se non è impostato o è impostato su false, il risultato delle connessioni ai backend di destinazione con certificati problematici dipende dall'impostazione di <IgnoreValidationErrors> (vedi sotto). Una risposta di successo (2xx) può verificarsi in determinate condizioni, se <IgnoreValidationErrors> è impostato su true.
<ClientAuthEnabled>	Consente TLS bidirezionale (noto anche come mutual TLS o mTLS) tra Apigee e il client API oppure tra Apigee e il backend di destinazione. L'abilitazione di TLS bidirezionale in genere richiede la configurazione di un truststore su Apigee e di un truststore.
<KeyStore>	Un keystore contenente le chiavi private utilizzate per l'autenticazione client in uscita
<KeyAlias>	L'alias specificato quando hai caricato un certificato e una chiave privata nell'archivio chiavi.
<TrustStore>	Un archivio chiavi contenente certificati server attendibili.
<IgnoreValidationErrors>	Indica se gli errori di convalida vengono ignorati. Se il sistema di backend utilizza SNI e restituisce un certificato con un nome distinto (DN) del soggetto che non corrisponde al nome host, non è possibile ignorare l'errore e la connessione non va a buon fine. Nota: se <Enforce> è impostato su true, il valore di <IgnoreValidationErrors> viene ignorato.
<Ciphers>	Crittografie supportate per TLS/SSL in uscita. Se non vengono specificate cifrature, saranno consentite tutte le cifrature disponibili per la JVM. Per limitare le cifrature, aggiungi i seguenti elementi che elencano le cifrature supportate: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>
<Protocols>	Protocolli supportati per TLS/SSL in uscita. Se non vengono specificati protocolli, saranno consentiti tutti i protocolli disponibili per la JVM. Per limitare i protocolli, specificali in modo esplicito. Ad esempio, per consentire solo TLS v1.2 o TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>

Informazioni sull'impostazione degli elementi <KeyStore> e <TrustStore>

Nell'esempio precedente, il keystore e il truststore vengono specificati utilizzando riferimenti, nel formato:

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

Avviso:Apigee consiglia vivamente di utilizzare sempre i riferimenti al keystore e al truststore. Un riferimento è una variabile che contiene il nome dell'archivio chiavi o dell'archivio attendibile, anziché specificare direttamente il nome dell'archivio chiavi. Se carichi un nuovo certificato che non utilizza un riferimento, ma specifica direttamente il nome del keystore, i processori di messaggi di runtime non rileveranno automaticamente la modifica. Per risolvere il problema, devi contattare l'assistenza Google Cloud per riavviare i Message Processor, il che potrebbe causare un degrado temporaneo del servizio.

In questo esempio:

• myKeystoreRef è un riferimento che contiene il nome dell'archivio chiavi. In questo esempio, il nome del keystore è myKeystore.
• myTruststoreRef è un riferimento che contiene il nome del truststore. In questo esempio, il nome del truststore è myTruststore.

Quando un certificato scade, devi aggiornare l'endpoint di destinazione/il server di destinazione per specificare il keystore o il truststore che contiene il nuovo certificato. Tuttavia, se utilizzi i riferimenti, puoi modificare il valore di references in modo che rifletta i nuovi nomi di keystore o truststore anziché modificare l'endpoint di destinazione/il server di destinazione. La modifica del valore del riferimento non richiede di contattare l'assistenza clienti Google Cloud.

In alternativa, puoi specificare direttamente il nome dell'archivio chiavi e del truststore:

<KeyStore>myKeystore</KeyStore>
<TrustStore>myTruststore</TrustStore>

Se specifichi direttamente il nome del keystore o del truststore, devi contattare l'assistenza clienti Google Cloud.

Una terza opzione è utilizzare le variabili di flusso:

<KeyStore>{ssl.keystore}</KeyStore>
<TrustStore>{ssl.truststore}</TrustStore>

Puoi utilizzare le variabili di flusso per specificare dinamicamente un keystore o un truststore, con un effetto simile all'utilizzo di un riferimento. Per ulteriori informazioni, vedi Utilizzo delle variabili di flusso per impostare dinamicamente i valori TLS/SSL.

Informazioni sulla configurazione di TLS

Tutti i clienti Apigee, sia a pagamento che di valutazione, hanno il controllo completo della configurazione degli endpoint di destinazione/dei server di destinazione. Inoltre, i clienti Apigee a pagamento hanno il controllo completo delle proprietà TLS.

Gestione dei certificati scaduti

Se un certificato TLS scade o se la configurazione del sistema cambia in modo che il certificato non sia più valido, devi aggiornarlo. Quando configuri TLS per un endpoint di destinazione/un server di destinazione, devi decidere come eseguire l'aggiornamento prima di eseguire qualsiasi configurazione.

Nota:non puoi aggiornare un keystore o un truststore esistente per aggiungere un nuovo certificato. Quando aggiorni un certificato, devi creare un nuovo keystore/truststore. In genere, crei il nuovo keystore/truststore e carichi il nuovo certificato prima che scada quello nel vecchio keystore/truststore. In questo modo puoi testare il nuovo keystore/truststore e ripristinare il vecchio keystore/truststore in caso di problemi.

Quando un certificato scade

Su Apigee, i certificati vengono archiviati in una delle due posizioni seguenti:

• Archivio chiavi: contiene il certificato TLS e la chiave privata utilizzati per identificare l'entità durante l'handshake TLS.
• Truststore: contiene i certificati attendibili su un client TLS utilizzati per convalidare il certificato di un server TLS presentato al client. Questi certificati sono in genere certificati autofirmati, certificati firmati da una CA attendibile o certificati utilizzati nell'ambito di TLS bidirezionale (noto anche come mutual TLS o mTLS).

Il metodo utilizzato per specificare il keystore e il truststore nell'endpoint di destinazione o nel server di destinazione determina la modalità di esecuzione dell'aggiornamento del certificato. Puoi utilizzare riferimenti, nomi diretti o variabili di flusso. Ogni metodo ha ripercussioni diverse sul processo di aggiornamento, come descritto nella tabella seguente:

Tipo di configurazione	Come aggiornare/sostituire il certificato	Utilizzo / Impatto
Riferimento (consigliato)	Archivio chiavi:crea un nuovo archivio chiavi con un nuovo nome e un alias con lo stesso nome del vecchio alias. Truststore:crea un truststore con un nuovo nome. Il nome dell'alias non è importante. Nota: se un certificato fa parte di una catena, devi creare un unico file contenente tutti i certificati e caricarlo in un singolo alias oppure caricare tutti i certificati della catena separatamente nel truststore utilizzando un alias diverso per ogni certificato.	Aggiorna il riferimento in modo che punti al nuovo store. Non è necessario contattare l'assistenza Apigee. Nessun tempo di inattività.
Variabile di flusso	Archivio chiavi:crea un nuovo archivio chiavi con un nuovo nome e un alias con lo stesso nome o un nuovo nome. Truststore:crea un truststore con un nuovo nome.	Trasmetti la variabile di flusso aggiornata in ogni richiesta con il nome del nuovo negozio. Non è necessario contattare l'assistenza Apigee. Nessun tempo di inattività.
Diretto	Metodo 1: crea un nuovo negozio (consigliato per evitare tempi di inattività) Crea un nuovo keystore o truststore con un nuovo nome e carica il nuovo certificato (e la chiave privata se crei un keystore).	Aggiorna la configurazione dell'endpoint di destinazione o del server di destinazione per specificare direttamente il nuovo nome del negozio, quindi esegui nuovamente il deployment del proxy API. Non è necessario contattare l'assistenza Apigee.
Diretto	Metodo 2a: aggiornamento in loco (eliminazione e ricreazione) Elimina il keystore o il truststore e ricrealo con lo stesso nome.	Le richieste API non andranno a buon fine durante il periodo di eliminazione e ricreazione. Poiché i processori di messaggi memorizzano nella cache gli archivi specificati direttamente, non rileveranno automaticamente il certificato aggiornato. Per riavviare i processori di messaggi, devi contattare l'assistenza clienti Google Cloud.
Diretto	Metodo 2b: aggiornamento in loco (caricamento dell'archivio attendibile) Per gli archivi attendibilità, carica un nuovo certificato direttamente nell'archivio attendibilità esistente.	Poiché i processori di messaggi memorizzano nella cache gli archivi specificati direttamente, non rileveranno automaticamente il nuovo certificato. Per riavviare i processori di messaggi, devi contattare l'assistenza clienti Google Cloud.