Configurazione dell'accesso TLS a un'API per il cloud privato

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Un host virtuale su Edge definisce i domini e le porte su cui viene esposto un proxy API e, per estensione, l'URL che le app utilizzano per accedere a un proxy API.

Un host virtuale definisce anche se si accede al proxy API utilizzando il protocollo HTTP o il protocollo HTTPS criptato che utilizza TLS. Quando configuri un host virtuale per utilizzare HTTPS e TLS, crei un host virtuale su Edge e lo configuri in modo che utilizzi un keystore e un truststore.

Scopri di più:

• Informazioni su TLS/SSL
• Utilizzare TLS con Edge
• Informazioni sugli host virtuali
• Configurazione degli host virtuali per Private Cloud
• Informazioni di riferimento sulle proprietà degli host virtuali
• Keystore e truststore

Requisiti per la creazione di un host virtuale

Prima di creare un host virtuale, devi disporre delle seguenti informazioni:

• Il nome di dominio visibile pubblicamente dell'host virtuale. Ad esempio, devi sapere se il nome visibile pubblicamente è api.myCompany.com, myapi.myCompany.com, e così via. Queste informazioni vengono utilizzate quando crei l'host virtuale e anche quando crei il record DNS per l' host virtuale.
• Per TLS unidirezionale, devi creare un keystore che contenga quanto segue:
  • Certificato TLS: un certificato firmato da un'autorità di certificazione (CA) o una catena di certificati in cui l'ultimo certificato è firmato da una CA.
  • Chiave privata: Edge supporta dimensioni delle chiavi fino a 2048 bit. Una passphrase è facoltativa.
• Per TLS bidirezionale, hai bisogno di un keystore e di un truststore per contenere il certificato del client e, facoltativamente, la catena di CA del certificato. Hai bisogno del truststore anche se il certificato è firmato da una CA.

Per saperne di più sulla creazione di keystore e truststore, consulta Keystore e Truststore.

Configurazione dell'host virtuale per TLS

Per creare un host virtuale, crea un oggetto XML che lo definisca. L'oggetto XML seguente utilizza l'elemento <SSLInfo> per definire un host virtuale per una configurazione TLS unidirezionale su HTTPS:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

In questo esempio, l'elemento <Enabled> è impostato su true per abilitare TLS unidirezionale, mentre gli elementi <KeyStore> e <KeyAlias> specificano il keystore e la chiave utilizzati dalla connessione TLS.

Per abilitare TLS bidirezionale, imposta l'elemento <ClientAuthEnabled> su true, e specifica un truststore utilizzando l'elemento <TrustStore>. Il truststore contiene il certificato del client e, facoltativamente, la catena di CA del certificato.

Decidere come specificare il nome del keystore e del truststore nell'host virtuale

Nell'esempio di host virtuale riportato sopra, hai specificato il keystore utilizzando un riferimento. Un riferimento è una variabile che contiene il nome del keystore, anziché specificare direttamente il nome del keystore.

Il vantaggio di utilizzare un riferimento è che puoi modificarne il valore per cambiare il keystore utilizzato dall'host virtuale, in genere perché il certificato nel keystore corrente scadrà a breve. La modifica del valore del riferimento non richiede il riavvio di Edge Router.

In alternativa, puoi utilizzare un nome keystore letterale nell'host virtuale. Tuttavia, se mai modifichi l'host virtuale per cambiare il nome del keystore, devi riavviare i router Edge.

Limitazioni nell'utilizzo dei riferimenti a keystore e truststore

Quando utilizzi i riferimenti a keystore e truststore, devi tenere conto della seguente limitazione:

• Puoi utilizzare i riferimenti a keystore e truststore negli host virtuali solo se supporti SNI e termini SSL sui router Apigee.
• Se hai un bilanciatore del carico davanti ai router Apigee e termini TLS sul bilanciatore del carico, non puoi utilizzare i riferimenti a keystore e truststore negli host virtuali.

Modificare un host virtuale esistente per utilizzare i riferimenti al keystore e al truststore

Apigee consiglia vivamente di utilizzare i riferimenti a keystore e truststore negli host virtuali. I riferimenti ti consentono di modificare il keystore e il truststore utilizzati dall'host virtuale senza dover riavviare i router Edge.

Se gli host virtuali sono attualmente configurati per utilizzare il nome letterale del keystore o del truststore, puoi convertirli in modo che utilizzino i riferimenti. Per farlo, aggiorna l'host virtuale in modo che utilizzi i riferimenti, quindi riavvia i router Edge.

Impostare le cifrature e i protocolli TLS per Edge 4.15.07 e versioni precedenti

Se utilizzi Edge versione 4.15.07 e precedenti, imposta il protocollo TLS e le cifrature utilizzate dall'host virtuale utilizzando i tag secondari <Ciphers> e <Protocols> del tag <SSLInfo>. Questi tag sono descritti nella tabella seguente.

Ad esempio:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

Il tag <Cipher> utilizza il nome della cifratura Java e JSSE. Ad esempio, per Java 8, vedi http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites.

Specificare le cifrature e i protocolli TLS per Edge 4.16.01-4.16.09

In Edge 4.16.01-4.16.09, imposti le cifrature e i protocolli predefiniti per gli host virtuali a livello globale sul router. Questi valori predefiniti vengono applicati a tutti gli host virtuali.

Utilizza i token per specificare i protocolli e le cifrature predefiniti:

• Per specificare i protocolli predefiniti, utilizza il token conf_load_balancing_load.balancing.driver.server.ssl.protocols
• Per specificare le cifrature predefinite per il router, utilizza il token conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Il valore predefinito del token conf_load_balancing_load.balancing.driver.server.ssl.protocols è:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

Questa impostazione specifica che il router supporta le versioni TLS 1.0, 1.1 e 1.2. Specifica un elenco di valori delimitati da spazi per il token.

Il valore predefinito del token conf_load_balancing_load.balancing.driver.server.ssl.ciphers è:

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

Questa impostazione specifica:

• Lunghezza della chiave di 128 bit o superiore richiesta (HIGH).
• Escludi le cifrature senza autenticazione (!aNULL)
• Escludi le suite di cifratura che utilizzano MD5 (!MD5)
• Escludi le suite di cifratura che utilizzano DH (inclusi DH anonimo, DH effimero e DH fisso) E triple DES (!DH+3DES)
• Escludi le suite di cifratura che utilizzano lo scambio di chiavi RSA E triple DES (!RSA+3DES)

Per informazioni sulla sintassi e sui valori consentiti da questo token, consulta Cifrature OpenSSL. Tieni presente che questo token utilizza i nomi delle cifrature OpenSSL, ad esempio AES128-SHA256, e non i nomi delle cifrature Java/JSSE, ad esempio TLS_RSA_WITH_AES_128_CBC_SHA256.

Per impostare il token per il router:

1. Modifica il file /opt/apigee/customer/application/router.properties. Se il file non esiste, crealo.
2. Imposta il conf_load_balancing_load.balancing.driver.server.ssl.ciphers token. Ad esempio, per specificare solo TLSv1.2 ed escludere le suite di cifratura che utilizzano chiavi precondivise, aggiungi!PSK:

   conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
   conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK

3. Assicurati che il file router.properties sia di proprietà di apigee:

   chown apigee:apigee /opt/apigee/customer/application/router.properties

4. Riavvia il router Edge:

   /opt/apigee/apigee-service/bin/apigee-service edge-router restart

5. Controlla il valore del token:

   /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Impostare i parametri dell'host virtuale TLS per Edge versione 4.17.01 e successive

Se utilizzi Edge versione 4.17.01 e successive, puoi impostare alcune proprietà TLS per un singolo host virtuale, come il protocollo e la cifratura TLS, utilizzando il tag secondario <Properties> del <VirtualHost> tag. Questi tag sono descritti in Informazioni di riferimento sulle proprietà degli host virtuali.

Ad esempio:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

Per informazioni sulla sintassi e sui valori consentiti dal token ssl_ciphers, consulta Cifrature OpenSSL. Tieni presente che questo token utilizza i nomi delle cifrature OpenSSL, ad esempio AES128-SHA256, e non i nomi delle cifrature Java/JSSE, ad esempio TLS_RSA_WITH_AES_128_CBC_SHA256.

Creare un host virtuale che utilizza HTTPS

Questo esempio specifica il keystore per l'host virtuale utilizzando un riferimento. L'utilizzo di un riferimento ti consente di modificare il keystore senza dover riavviare i router.

Per creare l'host virtuale:

1. Crea e configura un keystore denominato myTestKeystore utilizzando la procedura descritta qui: Keystore e truststore. Assicurati che il keystore utilizzi un nome alias di myKeyAlias per il certificato e la chiave privata.

2. Utilizza la seguente chiamata API POST per creare il riferimento denominato keystoreref al keystore che hai creato sopra:

   curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
     -d '<ResourceReference name="keystoreref">
       <Refers>myTestKeystore</Refers>
       <ResourceType>KeyStore</ResourceType>
     </ResourceReference>'
     -u email:password
   

   Il riferimento specifica il nome del keystore e il tipo di riferimento come KeyStore.

   Utilizza la seguente chiamata API GET per visualizzare il riferimento:

   curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
   

3. Crea l'host virtuale utilizzando l'API Crea un host virtuale, dove <ms-IP> è l'indirizzo IP o il nome di dominio del nodo del server di gestione.

   Assicurati di specificare il riferimento al keystore e l'alias della chiave corretti:

   curl -X POST -H "Content-Type:application/xml" \
     http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
     -d '<VirtualHost  name="newTLSTrustStore2">
       <HostAliases>
         <HostAlias>apiTLS.myCompany.com</HostAlias>
       </HostAliases>
       <Interfaces/>
       <Port>9005</Port>
       <OCSPStapling>off</OCSPStapling>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://keystoreref</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
     </VirtualHost>' \
     -u email:password

4. Crea un record DNS per l'host virtuale che corrisponda all'alias host.

5. Se hai proxy API esistenti, aggiungi l'host virtuale all'elemento <HTTPConnection> in the ProxyEndpoint. L'host virtuale viene aggiunto automaticamente a tutti i nuovi proxy API.

   Consulta Aggiornare un proxy API dopo aver creato un host virtuale in Informazioni sugli host virtuali.

Dopo aver aggiornato un proxy API in modo che utilizzi l'host virtuale e aver creato il record DNS per l'alias host , puoi accedere al proxy API come mostrato di seguito:

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

Ad esempio:

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

Creare e modificare i riferimenti a un keystore o a un truststore

Se vuoi, puoi configurare l'host virtuale in modo che utilizzi un riferimento al keystore o al truststore. Il vantaggio di utilizzare un riferimento è che puoi aggiornarlo in modo che punti a un keystore o a un truststore diverso per aggiornare il certificato TLS senza dover riavviare un router.

Ad esempio, di seguito è riportato un host virtuale che utilizza un riferimento al keystore:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Utilizza la seguente chiamata API POST per creare il riferimento denominato keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

Il riferimento specifica il nome del keystore e il relativo tipo.

Utilizza la seguente chiamata API GET per visualizzare il riferimento:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Per modificare in un secondo momento il riferimento in modo che punti a un keystore diverso, assicurandoti che l'alias abbia lo stesso nome, utilizza la seguente chiamata PUT:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password