Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Un cliente Cloud con un account a pagamento può creare un host virtuale in un'organizzazione.
Scopri di più:
- Informazioni sugli host virtuali
- Configurazione degli host virtuali
- Configurazione TLS
- Keystore e truststore
Chi può creare e modificare gli host virtuali nel cloud
La creazione e la modifica dell'host virtuale sono disponibili 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 dispongono dell'autorizzazione per creare host virtuali.
Ad esempio, i clienti paganti possono:
- Attiva TLS unidirezionale e bidirezionale
- Specifica l'archivio chiavi/l'archivio attendibilità utilizzato dall'host virtuale
Gli account senza costi e di prova non possono creare o modificare host virtuali e sono limitati agli host virtuali creati per loro al momento della registrazione a Edge. Per ulteriori informazioni sui piani tariffari Edge, consulta https://apigee.com/api-management/#/pricing.
Requisiti per la configurazione di un host virtuale per il cloud
La tabella seguente riassume i requisiti per la creazione di un host virtuale:
| Categoria | Requisito | Descrizione |
|---|---|---|
| Tipo di account | A pagamento | Gli account senza costi e di prova non possono creare o modificare host virtuali. |
| Ruolo utente | amministratore dell'organizzazione | Solo un amministratore dell'organizzazione può creare un host virtuale o un utente con un ruolo personalizzato che dispone delle autorizzazioni per modificare un host virtuale. |
| Numero di host virtuali | Massimo 20 |
Esiste un limite massimo di 20 host virtuali per organizzazione/ambiente nel cloud. Nota: non sono previsti limiti al numero di host virtuali nel cloud privato. La maggior parte delle organizzazioni e degli ambienti utilizza due host virtuali: uno per l'accesso HTTP e uno per l'accesso HTTPS. Potresti aver bisogno di host virtuali aggiuntivi se la tua organizzazione o il tuo ambiente consente l'accesso utilizzando nomi di dominio diversi. |
| URL di base | Include il protocollo | Quando definisci l'URL di base per l'host virtuale, nell'interfaccia utente o con l'API, devi specificare il protocollo (ad esempio "http://" o "https://") come parte dell'URL. |
| Porta | 443 |
Puoi creare un host virtuale solo sulla porta 443. Tieni presente che puoi creare più host virtuali sulla porta 443, purché dispongano di alias host univoci e supportino tutti TLS. |
| TLS | Obbligatorio |
Puoi creare solo un host virtuale che supporti TLS su HTTPS. Devi aver già creato un archivio chiavi e, facoltativamente, un archivio attendibilità contenente il certificato e la chiave TLS. Devi disporre di un certificato firmato da un'entità attendibile, ad esempio Symantec o VeriSign. Non puoi utilizzare un certificato autofirmato. Se hai bisogno di accesso HTTP, contatta l'assistenza Apigee Edge. |
| Protocollo TLS | TLS 1.2 |
Edge nel cloud supporta solo TLS versione 1.2. |
| Alias host | Unico nell'organizzazione e nell'ambiente | L'alias host non esiste per un'altra combinazione organizzazione/ambiente. |
| Nome di dominio | Di proprietà del cliente |
Devi essere il proprietario del nome di dominio specificato nell'host virtuale. Controlli Edge per assicurarsi che il nome di dominio, come definito dall'alias host, corrisponda ai metadati nel certificato TLS. In particolare, Edge controlla le seguenti informazioni nel certificato:
I caratteri jolly sono consentiti nella SAN o CN, ad esempio Inoltre, Edge verifica che il certificato non sia scaduto. |
| Supporto SNI dell'app client | Tutte le app client che accedono all'host virtuale devono supportare SNI. |
Il supporto SNI è richiesto per tutte le app. |
Creare un host virtuale utilizzando un browser
La maggior parte degli esempi in questa sezione utilizza l'API Edge per creare o modificare host virtuali, ma puoi creare un host virtuale nella UI Edge.
Per creare un host virtuale utilizzando l'interfaccia utente Edge:
- Accedi ad apigee.com/edge.
- Seleziona Amministratore > Host virtuali.
- Seleziona l'ambiente, ad esempio prod o test.
- Seleziona + Host virtuale per creare un host virtuale o seleziona il nome di un host virtuale esistente per modificarlo.
- Per informazioni dettagliate su come completare i 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:
- Per nome, specifica 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. Si tratta del 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 il valore viene omesso, per impostazione predefinita la porta viene impostata su 443.
- Abilita TLS in base alle esigenze.
L'elemento<Enable>è impostato su true per abilitare TLS unidirezionale, mentre gli elementi<KeyStore>specificano l'archivio chiavi e l'alias chiave utilizzati dalla connessione TLS.
Per abilitare TLS bidirezionale, imposta<ClientAuthEnabled>su true e specifica un archivio attendibilità utilizzando l'elemento<TrustStore>. L'archivio attendibilità contiene l'emittente del certificato del client e la catena di CA del certificato, che è obbligatoria.
Nota: poiché Edge supportava originariamente SSL, il tag che utilizzi per configurare TLS è denominato<SSLInfo>.
Tieni presente che esistono altre proprietà che puoi impostare nell'host virtuale. Per un riferimento per tutte le proprietà, consulta la sezione Riferimento per le proprietà dell'host virtuale.
Decidere come specificare il nome dell'archivio chiavi e dell'archivio attendibilità nell'host virtuale
Quando configuri un host virtuale per supportare TLS, devi specificare un archivio chiavi 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 dell'utilizzo di un riferimento è che puoi modificare il valore del riferimento per modificare l'archivio chiavi utilizzato dall'host virtuale, di solito perché il certificato nell'archivio chiavi corrente scadrà nel prossimo futuro. La modifica del valore del riferimento non richiede il riavvio del router perimetrale. Consulta Utilizzo dei riferimenti per ulteriori informazioni sulla creazione e sulla modifica dei riferimenti.
Puoi utilizzare solo un riferimento all'archivio chiavi e all'archivio attendibilità; non puoi utilizzare un riferimento all'alias. Quando modifichi il riferimento a un archivio chiavi, assicurati che il nome alias del certificato sia lo stesso dell'archivio chiavi precedente.
Limitazioni nell'utilizzo dei riferimenti agli archivi chiavi e all'archivio attendibilità
Quando utilizzi i riferimenti ad archivi chiavi e truststore, devi tenere conto della seguente limitazione:
- Puoi utilizzare i riferimenti dell'archivio chiavi e dell'archivio attendibilità negli host virtuali solo se supporti SNI e termini SSL sui router Apigee.
- Se disponi di un bilanciatore del carico davanti ai router Apigee e termini TLS sul bilanciatore del carico, non puoi utilizzare i riferimenti dell'archivio chiavi e dell'archivio attendibilità negli host virtuali.
Definizione di un host virtuale per TLS bidirezionale
Per abilitare TLS bidirezionale, imposta l'elemento <ClientAuthEnabled> su
true e specifica un archivio attendibilità
utilizzando un riferimento con l'elemento <TrustStore>. L'archivio attendibilità contiene l'emittente del certificato del client e la catena di CA del certificato, che è obbligatoria. Il client deve inoltre essere configurato correttamente per il protocollo TLS a due vie.
Per creare un host virtuale per TLS bidirezionale, crea un oggetto XML che definisca 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:
- Attiva TLS bidirezionale impostando
<ClientAuthEnabled>su true. - Specifica il riferimento all'archivio attendibilità utilizzando l'elemento
<TrustStore>. L'archivio attendibilità contiene l'emittente del certificato del client e la catena di CA del certificato, che è obbligatoria.
Definizione di un host virtuale che utilizza il certificato e la chiave della prova senza costi di Apigee
Se disponi di un account Edge per Cloud a pagamento e non disponi ancora di un certificato e 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 archivio chiavi.
Il certificato della prova senza costi di Apigee è definito per un dominio di *.apigee.net. Pertanto, <HostAlias> dell'host virtuale deve essere anch'esso nel formato *.apigee.net.
Se esegui TLS bidirezionale, devi comunque impostare l'elemento <ClientAuthEnabled> su
true e specificare un archivio attendibilità utilizzando un riferimento con l'elemento <TrustStore>, come descritto sopra in Definizione di un host virtuale per TLS a due vie.
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 a due vie, 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 di Edge, seleziona l'opzione Utilizza certificato di prova senza costi integrato durante la creazione dell'host virtuale per utilizzare il certificato e la chiave Apigee senza costi:
Creazione di un host virtuale
Utilizza la procedura seguente per creare l'host virtuale:
- Per questo esempio, crea una voce DNS e un record CNAME per il dominio rivolto al pubblico,
api.myCompany.com, che rimandi a[org]-[environment].apigee.net. - Crea e configura un archivio chiavi, denominato myTestKeystore in questo esempio, utilizzando la procedura descritta qui: Creazione di archivi chiavi e dell'archivio attendibilità mediante l'interfaccia utente Edge. Per questo esempio, assicurati che l'archivio chiavi utilizzi un nome alias di myKeyAlias per il certificato e la chiave privata.
- Carica il certificato e la chiave nell'archivio chiavi. Assicurati che il nome di dominio specificato dal certificato corrisponda all'alias host che vuoi utilizzare per l'host virtuale.
-
Crea un riferimento all'archivio chiavi utilizzando la UI o l'API Edge. Il riferimento specifica il nome dell'archivio chiavi e il tipo di riferimento come
KeyStore. Consulta Utilizzo dei riferimenti per ulteriori informazioni sulla creazione e sulla modifica dei riferimenti. - Crea l'host virtuale utilizzando l'API Create a Virtual Host (Crea un host virtuale). Assicurati di specificare il riferimento all'archivio chiavi e l'alias chiave corretti.
Per utilizzare l'API, usa la seguente chiamata API POST per creare l'archivio chiavi 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:passwordSe esegui TLS bidirezionale con il client, imposta
<ClientAuthEnabled>su true e specifica l'archivio attendibilità utilizzando l'elemento<TrustStore>. Il client deve essere configurato correttamente per TLS bidirezionale, il che significa che Edge ha un archivio attendibilità contenente l'emittente di certificati e la catena di certificati del client. Crea l'archivio attendibilità utilizzando la procedura descritta qui: Creazione di archivi chiavi e archivio attendibilità con l'interfaccia utente perimetrale. Se disponi di 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 la sezione 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
Le attività principali che i clienti Cloud a pagamento eseguono per modificare un host virtuale esistente:
- Modifica del valore di un riferimento a un archivio chiavi o a un archivio attendibilità.
Nota: dopo aver impostato<KeyStore>o<TrustStore>per l'utilizzo di un riferimento, puoi modificare il valore del riferimento in qualsiasi momento. Tuttavia, se desideri cambiare<KeyStore>o<TrustStore>per utilizzare un riferimento diverso o cambiare<KeyAlias>per utilizzare un alias diverso, devi contattare l'assistenza Apigee Edge. - Modifica delle proprietà TLS dell'host virtuale.
Modifica del valore di un riferimento
Puoi modificare il valore di un riferimento per cambiare l'archivio chiavi o l'archivio attendibilità utilizzato da un host virtuale.
Prima di modificare il valore del riferimento:
- Crea un nuovo archivio chiavi e carica un certificato e una chiave come descritto in Creazione di keystore e truststore mediante l'interfaccia utente Edge. Nel nuovo archivio chiavi assicurati di utilizzare per l'alias chiave lo stesso nome utilizzato nell'archivio chiavi esistente.
- Se necessario, crea un nuovo archivio attendibilità e carica un certificato come descritto in Creazione di archivi chiavi e di un archivio attendibilità tramite l'interfaccia utente Edge.
- Modifica il riferimento come descritto in Utilizzo dei riferimenti.
Modifica delle proprietà TLS dell'host virtuale
I clienti a pagamento possono utilizzare l'API Update a Virtual Host per aggiornare un host virtuale. Questa API consente di impostare tutte le proprietà per l'host virtuale descritte nella sezione Riferimento proprietà host virtuale.
Quando modifichi l'host virtuale, Edge esegue una convalida simile a quando crei un host virtuale. In altre parole, durante 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à. In particolare, Edge verifica che le seguenti informazioni nel certificato corrispondano all'alias host:
- CN - Nome comune
- SAN - Nome alternativo del soggetto
- Edge verifica che il certificato non sia scaduto.
Per modificare un host virtuale utilizzando l'API Edge, esegui queste operazioni:
Aggiorna l'host virtuale utilizzando l'API Update a Virtual Host (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, devi impostare 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 all'archivio chiavi e all'archivio attendibilità
Tutti i nuovi host virtuali per Edge nel cloud utilizzano il riferimento all'archivio chiavi e all'archivio attendibilità. I riferimenti consentono di modificare l'archivio chiavi e l'archivio attendibilità senza contattare l'assistenza Apigee Edge.
Gli host virtuali meno recenti su Apigee Edge potrebbero non essere configurati per l'utilizzo dei riferimenti per archivi chiavi e archivi attendibilità. In questo caso, puoi aggiornare l'host virtuale in modo che utilizzi un riferimento.
Aggiornamento di un host virtuale per utilizzare un riferimento
Utilizza la seguente procedura per aggiornare l'host virtuale:
- Se necessario, crea un nuovo archivio chiavi e carica un certificato come descritto in Creazione di archivi chiavi e di truststore mediante l'interfaccia utente Edge. Se hai già un archivio chiavi, puoi configurare un riferimento che rimandi a quest'ultimo.
- Crea un nuovo riferimento all'archivio chiavi.
- Se necessario, crea un nuovo archivio attendibilità e carica un certificato. Se hai già un archivio attendibilità, puoi configurare un riferimento che punti a quell'archivio.
- Crea un nuovo riferimento all'archivio attendibilità.
- Aggiorna l'host virtuale per impostare l'archivio chiavi, l'alias, l'archivio attendibilità e qualsiasi altra proprietà TLS. Il payload per la 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 - Contatta l'assistenza Apigee per riavviare i router Edge e completare il processo.