Configurazione degli host virtuali per il cloud

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

Un cliente Cloud con un account a pagamento può creare un host virtuale in un'organizzazione.

• Informazioni sugli host virtuali
• Configurazione degli host virtuali
• Configurazione di TLS
• Keystore e Truststore

Chi può creare e modificare gli host virtuali nel cloud

La creazione e la modifica di host virtuali è disponibile per gli account a pagamento solo in Edge Cloud. L'utente che crea l'host virtuale deve avere il ruolo di amministratore dell'organizzazione o un ruolo personalizzato con autorizzazioni per modificare un host virtuale. Gli utenti con altri ruoli non sono autorizzati a creare host virtuali.

Ad esempio, i clienti a pagamento possono:

• Abilita TLS unidirezionale e bidirezionale
• Specifica il keystore/truststore utilizzato dall'host virtuale

Gli account di prova e senza costi non possono creare o modificare host virtuali e sono limitati agli host virtuali creati per loro al momento della registrazione di Edge. Per saperne di più sui piani tariffari di Edge, visita la pagina https://apigee.com/api-management/#/pricing.

Requisiti per la configurazione di un host virtuale per il cloud

La seguente tabella riassume i requisiti per la creazione di un host virtuale:

Crea un host virtuale utilizzando un browser

La maggior parte degli esempi in questa sezione utilizza l'API Edge per creare o modificare gli host virtuali, ma puoi creare un host virtuale nell'interfaccia utente Edge.

Per creare un host virtuale utilizzando la UI Edge:

1. Accedi a apigee.com/edge.
2. Seleziona Amministratore > Host virtuali.
3. Seleziona l'ambiente, ad esempio prod o test.
4. Seleziona + Host virtuale per creare un host virtuale o seleziona il nome di un host virtuale esistente per modificarlo.
5. Per informazioni dettagliate sulla compilazione dei campi dell'host virtuale, consulta la tabella riportata sopra.

Definizione di un host virtuale per TLS unidirezionale

Un oggetto XML che definisce l'host virtuale. Ad esempio, il seguente oggetto XML definisce un host virtuale per TLS unidirezionale:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

In questa definizione:

• Specifica name come myTLSVHost. Utilizza il nome per fare riferimento all'host virtuale in un proxy API o in una chiamata API.
• Specifica l'alias host come api.myCompany.com. Questo è il dominio pubblico utilizzato per accedere alle tue API come definito da una definizione DNS e da un record CNAME.
• Specifica il numero di porta come 443. Se viene omesso, per impostazione predefinita la porta è impostata su 443.
• Abilita TLS come richiesto.
  
  L'elemento <Enable> è impostato su true per abilitare TLS unidirezionale, mentre gli elementi <KeyStore> specificano il keystore e l'alias della chiave utilizzati dalla connessione TLS.
  
  Per attivare TLS bidirezionale, imposta <ClientAuthEnabled> su true e specifica un truststore utilizzando l'elemento <TrustStore>. Il truststore contiene l'emittente del certificato del client e la catena CA del certificato, che è obbligatoria.
  
  Nota:poiché Edge supportava originariamente SSL, il tag che utilizzi per configurare TLS è denominato <SSLInfo>.

Tieni presente che puoi impostare altre proprietà nell'host virtuale. Per un riferimento a tutte le proprietà, consulta Riferimento alle proprietà dell'host virtuale.

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

Quando configuri un host virtuale per supportare TLS, specifichi un keystore utilizzando un riferimento. Un riferimento è una variabile che contiene il nome dell'archivio chiavi o dell'archivio attendibilità, anziché specificare direttamente il nome dell'archivio chiavi o dell'archivio attendibilità, come mostrato di seguito:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>

Il vantaggio di utilizzare un riferimento è che puoi modificarne il valore per cambiare il keystore utilizzato dall'host virtuale, di solito perché il certificato nel keystore corrente scadrà a breve. La modifica del valore del riferimento non richiede il riavvio dell'Edge Router. Per saperne di più su come creare e modificare i riferimenti, consulta Utilizzare i riferimenti.

Puoi utilizzare solo un riferimento al keystore e al truststore; non puoi utilizzare un riferimento all'alias. Quando modifichi il riferimento a un keystore, assicurati che il nome alias del certificato sia lo stesso del keystore precedente.

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 al keystore e al truststore negli host virtuali.

Definizione di un host virtuale per TLS bidirezionale

Per abilitare TLS bidirezionale, imposta l'elemento <ClientAuthEnabled> su true e specifica un truststore utilizzando un riferimento con l'elemento <TrustStore>. Il truststore contiene l'emittente del certificato del client e la catena CA del certificato, che è obbligatoria. Il client deve anche essere configurato correttamente per TLS bidirezionale.

Per creare un host virtuale per TLS bidirezionale, crea un oggetto XML che definisce l'host virtuale:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
</VirtualHost>

In questa definizione:

• Abilita TLS bidirezionale impostando <ClientAuthEnabled> su true.
• Specifica il riferimento al truststore utilizzando l'elemento <TrustStore>. Il truststore contiene l'emittente del certificato del client e la catena CA del certificato, che è obbligatoria.

Definizione di un host virtuale che utilizza il certificato e la chiave della prova senza costi di Apigee

Se hai un account Edge for Cloud a pagamento e non disponi ancora di un certificato e di una chiave TLS, puoi creare un host virtuale che utilizza il certificato e la chiave della prova senza costi di Apigee. Ciò significa che puoi creare l'host virtuale senza prima creare un keystore.

Il certificato di prova senza costi di Apigee è definito per un dominio di *.apigee.net. Pertanto, anche <HostAlias> dell'host virtuale deve essere nel formato *.apigee.net.

Se esegui TLS bidirezionale, devi comunque impostare l'elemento <ClientAuthEnabled> su true e specificare un truststore utilizzando un riferimento con l'elemento <TrustStore> come descritto sopra in Definizione di un host virtuale per TLS bidirezionale.

Un oggetto XML che definisce l'host virtuale utilizzando il certificato e la chiave della prova senza costi di Apigee omette gli elementi <KeyStore> e <KeyAlias> e li sostituisce con l'elemento <UseBuiltInFreeTrialCert>, come mostrato di seguito:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

Il valore predefinito dell'elemento <UseBuiltInFreeTrialCert> è false.

Per TLS bidirezionale, definisci l'host virtuale come:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

Nell'interfaccia utente Edge, seleziona l'opzione Utilizza il certificato di prova senza costi integrato quando crei l'host virtuale per utilizzare il certificato e la chiave Apigee senza costi:

Creazione di un host virtuale

Utilizza la seguente procedura per creare l'host virtuale:

1. Crea una voce DNS e un record CNAME per il tuo dominio pubblico, api.myCompany.com in questo esempio, che rimanda a [org]-[environment].apigee.net.
2. Crea e configura un keystore, denominato myTestKeystore in questo esempio, utilizzando la procedura descritta qui: Creazione di keystore e truststore utilizzando la UI Edge. Per questo esempio, assicurati che il keystore utilizzi il nome alias myKeyAlias per il certificato e la chiave privata.
3. Carica il certificato e la chiave nell'archivio chiavi. Assicurati che il nome di dominio specificato dal tuo certificato corrisponda all'alias host che vuoi utilizzare per l'host virtuale.

4. Crea un riferimento al keystore utilizzando l'API o la UI Edge. Il riferimento specifica il nome del keystore e il tipo di riferimento come KeyStore. Consulta Utilizzo dei riferimenti per ulteriori informazioni sulla creazione e la modifica dei riferimenti.

5. Crea l'host virtuale utilizzando l'API Create a Virtual Host. Assicurati di specificare il riferimento al keystore e l'alias della chiave corretti. Per utilizzare l'API, utilizza la seguente chiamata API POST per creare il keystore denominato myTLSVHost:

   curl -X POST -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \
     -d '<VirtualHost name="myTLSVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Port>443</Port>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://myTestKeystoreRef</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
     </VirtualHost>' \
     -u orgAdminEmail:password

   Se esegui TLS bidirezionale con il client, imposta <ClientAuthEnabled> su true e specifica il truststore utilizzando l'elemento <TrustStore>. Il client deve essere configurato correttamente per TLS bidirezionale, il che significa che Edge ha un truststore contenente l'emittente del certificato e la catena di certificati del client. Crea il truststore utilizzando la procedura descritta qui: Creazione di keystore e truststore utilizzando l'UI di Edge.

6. Se hai proxy API esistenti, aggiungi l'host virtuale all'elemento <HTTPConnection> in ProxyEndpoint. L'host virtuale viene aggiunto automaticamente a tutti i nuovi proxy API. Consulta Configurazione di un proxy API per l'utilizzo di un host virtuale.

Dopo aver aggiornato un proxy API per utilizzare l'host virtuale e aver creato la voce DNS e il record CNAME per l'alias host, puoi accedere al proxy API come mostrato di seguito:

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

Ad esempio:

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

Modifica di un host virtuale

I clienti Cloud a pagamento eseguono due attività principali per modificare un host virtuale esistente:

1. Modifica del valore di un riferimento a un keystore o a un truststore.
   
   Nota: una volta impostato un <KeyStore> o un <TrustStore> da utilizzare come riferimento, puoi modificare il valore del riferimento in qualsiasi momento. Tuttavia, se vuoi modificare <KeyStore> o <TrustStore> per utilizzare un riferimento diverso oppure modificare <KeyAlias> per utilizzare un alias diverso, devi contattare l'assistenza Apigee Edge.
2. Modifica delle proprietà TLS dell'host virtuale.

Modifica del valore di un riferimento

Puoi modificare il valore di un riferimento per cambiare il keystore o il truststore utilizzato da un host virtuale.

Prima di modificare il valore del riferimento:

1. Crea un nuovo keystore e carica un certificato e una chiave come descritto in Creazione di keystore e truststore utilizzando l'interfaccia utente Edge. Nel nuovo keystore, assicurati di utilizzare lo stesso nome per l'alias della chiave utilizzato nel keystore esistente.
2. Se necessario, crea un nuovo truststore e carica un certificato come descritto in Creazione di keystore e truststore utilizzando l'interfaccia utente Edge.
3. Modifica il riferimento come descritto in Utilizzo dei riferimenti.

Modifica delle proprietà TLS dell'host virtuale

I clienti a pagamento possono utilizzare l'API Aggiorna un host virtuale per aggiornare un host virtuale. Questa API consente di impostare tutte le proprietà dell'host virtuale descritto in Riferimento alle proprietà dell'host virtuale.

Quando modifichi l'host virtuale, Edge esegue una convalida simile a quella eseguita quando crei un host virtuale. ovvero, in una modifica, Edge verifica che:

• Il dominio specificato dall'alias host non viene utilizzato in un'altra organizzazione e in un altro ambiente.
• Il nome di dominio è di tua proprietà. Nello specifico, Edge verifica che le seguenti informazioni nel certificato corrispondano all'alias host:
  • CN - Common Name
  • SAN - Subject Alternative Name
  • Edge verifica che il certificato non sia scaduto.

Per modificare un host virtuale utilizzando l'API Edge, procedi nel seguente modo:

1. Aggiorna l'host virtuale utilizzando l'API Aggiorna un host virtuale. Quando utilizzi l'API, devi specificare la definizione completa dell'host virtuale nel corpo della richiesta, non solo gli elementi che vuoi modificare. In questo esempio, imposti il valore della proprietà proxy_read_timeout:

   curl -X PUT -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
     -d '<VirtualHost name="myTLSVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Port>443</Port>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://myTestKeystoreRef</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
       <Properties>
          <Property name="proxy_read_timeout">50</Property>
            </Properties>
     </VirtualHost>' \
     -u orgAdminEmail:password

Modifica di un host virtuale per utilizzare i riferimenti al keystore e al truststore

Tutti i nuovi host virtuali per Edge in the Cloud utilizzano il riferimento al keystore e al truststore. I riferimenti ti consentono di modificare il keystore e il truststore senza contattare l'assistenza Apigee Edge.

Gli host virtuali precedenti su Apigee Edge potrebbero non essere configurati per utilizzare i riferimenti per i keystore e i truststore. In questo caso, puoi aggiornare l'host virtuale in modo che utilizzi un riferimento.

Aggiornamento di un host virtuale per utilizzare un riferimento

Per aggiornare l'host virtuale, segui questa procedura:

1. Se necessario, crea un nuovo keystore e carica un certificato come descritto in Creazione di keystore e truststore utilizzando l'interfaccia utente Edge. Se hai già un keystore, puoi configurare un riferimento che lo indichi.
2. Crea un nuovo riferimento al keystore.
3. Se necessario, crea un nuovo truststore e carica un certificato. Se hai già un truststore, puoi configurare un riferimento che lo indichi.
4. Crea un nuovo riferimento al truststore.
5. Aggiorna l'host virtuale per impostare il keystore, l'alias, il truststore e qualsiasi altra proprietà TLS. Il payload della chiamata è:

   curl -X PUT -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
     -d '<VirtualHost  name="myTLSVHost">
           <HostAliases>
             <HostAlias>api.myCompany.com</HostAlias>
           </HostAliases>
           <Port>443</Port>
           <OCSPStapling>off</OCSPStapling>
           <SSLInfo>
             <Enabled>true</Enabled>
             <ClientAuthEnabled>true</ClientAuthEnabled>
             <KeyStore>ref://myKeyStore2Way</KeyStore>
             <KeyAlias>keyAlias</KeyAlias>
             <TrustStore>ref://myTrustStore2Way</TrustStore>
             <IgnoreValidationErrors>false</IgnoreValidationErrors>
           </SSLInfo>
         </VirtualHost>' \
       -u orgAdminEmail:pWord

6. Contatta l'assistenza Apigee per riavviare i router Edge e completare la procedura.