Vous consultez la documentation d'Apigee Edge.
Consultez la
documentation Apigee X. en savoir plus
Un client Cloud disposant d'un compte payant peut créer un hôte virtuel dans une organisation.
En savoir plus :
- À propos des hôtes virtuels
- Configurer des hôtes virtuels
- Configuration de TLS
- Keystores et Truststores
Qui peut créer et modifier des hôtes virtuels dans le cloud
La création et la modification d'hôtes virtuels sont disponibles pour les comptes payants uniquement dans Edge Cloud. L'utilisateur qui crée l'hôte virtuel doit avoir le rôle d'administrateur de l'organisation ou un rôle personnalisé disposant des autorisations nécessaires pour modifier un hôte virtuel. Les utilisateurs disposant d'autres rôles ne sont pas autorisés à créer des hôtes virtuels.
Par exemple, les clients payants peuvent:
- Activer le protocole TLS unidirectionnel et bidirectionnel
- Spécifier le keystore/truststore utilisé par l'hôte virtuel
Les comptes sans frais et d'essai ne peuvent pas créer ni modifier d'hôtes virtuels et sont limités aux hôtes virtuels créés pour eux au moment de l'enregistrement Edge. Pour plus d'informations sur les forfaits Edge, consultez la page https://apigee.com/api-management/#/pricing.
Conditions requises pour la configuration d'un hôte virtuel
Le tableau suivant récapitule les conditions requises pour créer un hôte virtuel:
| Catégorie | Exigence | Description |
|---|---|---|
| Type de compte | Payant | Les comptes sans frais et d'essai ne peuvent pas créer ni modifier d'hôtes virtuels. |
| Rôle d'utilisateur | administrateur de l'organisation | Seul un administrateur de l'organisation peut créer un hôte virtuel ou un utilisateur doté d'un rôle personnalisé et autorisé à modifier un hôte virtuel. |
| Nombre d'hôtes virtuels | 20 au maximum |
Vous êtes limité à un maximum de 20 hôtes virtuels par organisation/environnement dans le cloud. Remarque: Le nombre d'hôtes virtuels dans le cloud privé n'est pas limité. La plupart des organisations/environnements utilisent deux hôtes virtuels: un pour HTTP et un pour l'accès HTTPS. Vous aurez peut-être besoin d'hôtes virtuels supplémentaires si votre organisation ou votre environnement autorise l'accès à l'aide de noms de domaine différents. |
| URL de base | Inclut le protocole | Lorsque vous définissez l'URL de base de l'hôte virtuel, que ce soit dans l'UI ou à l'aide de l'API, vous devez spécifier le protocole (par exemple, "http://" ou "https://") dans l'URL. |
| Port | 443 |
Vous ne pouvez créer un hôte virtuel que sur le port 443. Notez que vous pouvez créer plusieurs hôtes virtuels sur le port 443, à condition qu'ils possèdent des alias d'hôte uniques et qu'ils soient tous compatibles avec le protocole TLS. |
| TLS | Obligatoire |
Vous ne pouvez créer qu'un hôte virtuel compatible avec TLS via HTTPS. Vous devez avoir déjà créé un keystore et éventuellement un Truststore contenant votre certificat et votre clé TLS. Votre certificat doit être signé par une entité de confiance telle que Symantec ou VeriSign. Vous ne pouvez pas utiliser de certificat autosigné. Si vous avez besoin d'un accès HTTP, contactez l'assistance Apigee Edge. |
| Protocole TLS | TLS 1.2 |
Edge dans le cloud n'est compatible qu'avec la version 1.2 de TLS. |
| Alias de l'hôte | Unique dans l'organisation et l'environnement | L'alias d'hôte n'existe pas pour une autre combinaison organisation/environnement. |
| Nom de domaine | Appartenant au client |
Vous devez être le propriétaire du nom de domaine spécifié dans l'hôte virtuel. Edge vérifie que le nom de domaine, tel que défini par l'alias d'hôte, correspond aux métadonnées du certificat TLS. Plus précisément, Edge vérifie les informations suivantes dans le certificat:
Les caractères génériques sont autorisés dans le SAN ou le CN (par exemple, Edge vérifie également que le certificat n'a pas expiré. |
| Compatibilité SNI de l'application cliente | Toutes les applications clientes accédant à l'hôte virtuel doivent être compatibles avec la SNI. |
La compatibilité SNI est requise par toutes les applications. |
Créer un hôte virtuel à l'aide d'un navigateur
La plupart des exemples de cette section utilisent l'API Edge pour créer ou modifier des hôtes virtuels, mais vous pouvez créer un hôte virtuel dans l'interface utilisateur Edge.
Pour créer un hôte virtuel à l'aide de l'interface utilisateur Edge:
- Connectez-vous à apigee.com/edge.
- Sélectionnez Admin > Virtual Hosts (Admin > Hôtes virtuels).
- Sélectionnez l'environnement, par exemple prod ou test.
- Sélectionnez + Hôte virtuel pour créer un hôte virtuel ou sélectionnez le nom d'un hôte virtuel existant pour le modifier.
- Consultez le tableau ci-dessus pour obtenir des informations détaillées sur le remplissage des champs d'hôte virtuel.
Définir un hôte virtuel pour le protocole TLS unidirectionnel
Objet XML qui définit l'hôte virtuel. Par exemple, l'objet XML suivant définit un hôte virtuel pour le protocole TLS unidirectionnel:
<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>
Dans cette définition:
- Indiquez myTLSVHost dans le champ name. Utilisez ce nom pour référencer l'hôte virtuel dans un proxy d'API ou dans un appel d'API.
- Indiquez api.myCompany.com comme alias d'hôte. Il s'agit du domaine public utilisé pour accéder à vos API, tel que défini par une définition DNS et un enregistrement CNAME.
- Indiquez 443 comme numéro de port. Si cette valeur est omise, le port est défini par défaut sur 443.
- Activez le protocole TLS si nécessaire.
L'élément<Enable>est défini sur "true" pour activer le protocole TLS à sens unique, et les éléments et<KeyStore>spécifient le keystore et l'alias de clé utilisés par la connexion TLS.
Pour activer le protocole TLS bidirectionnel, définissez<ClientAuthEnabled>sur "true" et spécifiez un magasin de confiance à l'aide de l'élément<TrustStore>. Le Truststore contient l'émetteur du certificat du client et la chaîne d'autorité de certification du certificat, ce qui est obligatoire.
Remarque:Comme Edge était à l'origine compatible avec SSL, le tag que vous utilisez pour configurer TLS s'appelle<SSLInfo>.
Notez que vous pouvez définir des propriétés supplémentaires dans l'hôte virtuel. Pour en savoir plus sur toutes les propriétés, consultez la documentation de référence sur les propriétés d'hôte virtuel.
Décider de la manière de spécifier le nom du keystore et du truststore dans l'hôte virtuel
Lorsque vous configurez un hôte virtuel pour qu'il soit compatible avec TLS, vous spécifiez un keystore à l'aide d'une référence. Une référence est une variable qui contient le nom du keystore ou du truststore, au lieu de spécifier directement le nom du keystore ou du truststore, comme indiqué ci-dessous:
<SSLInfo>
<Enabled>true</Enabled>
<ClientAuthEnabled>false</ClientAuthEnabled>
<KeyStore>ref://myTestKeystoreRef</KeyStore>
<KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>
L'avantage d'utiliser une référence est que vous pouvez modifier sa valeur pour modifier le keystore utilisé par l'hôte virtuel, généralement parce que le certificat du keystore actuel expire dans un avenir proche. La modification de la valeur de référence ne nécessite pas de redémarrer le routeur Edge. Consultez la section Utiliser des références pour en savoir plus sur la création et la modification de références.
Vous ne pouvez utiliser qu'une référence au keystore et au truststore. Vous ne pouvez pas utiliser de référence à l'alias. Lorsque vous modifiez la référence dans un keystore, assurez-vous que le nom d'alias du certificat est identique à celui de l'ancien keystore.
Restrictions d'utilisation des références aux keystores et aux Trustedstores
Vous devez prendre en compte la restriction suivante lorsque vous utilisez des références à des keystores et à des Truststores:
- Vous ne pouvez utiliser des références de keystore et de Trustedstore dans des hôtes virtuels que si vous êtes compatible avec l'extension SNI et que vous arrêtez le protocole SSL sur les routeurs Apigee.
- Si vous disposez d'un équilibreur de charge devant les routeurs Apigee et que vous interrompez le protocole TLS au niveau de l'équilibreur de charge, vous ne pouvez pas utiliser de références à un keystore et à un magasin de confiance dans les hôtes virtuels.
Définir un hôte virtuel pour le protocole TLS bidirectionnel
Pour activer le protocole TLS bidirectionnel, définissez l'élément <ClientAuthEnabled> sur true et spécifiez un magasin de confiance à l'aide d'une référence avec l'élément <TrustStore>. Le Truststore contient l'émetteur du certificat du client et la chaîne d'autorité de certification du certificat, ce qui est obligatoire. Le client doit également être correctement configuré pour le protocole TLS bidirectionnel.
Pour créer un hôte virtuel pour le protocole TLS bidirectionnel, créez un objet XML qui définit l'hôte virtuel:
<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>
Dans cette définition:
- Activez le protocole TLS bidirectionnel en définissant
<ClientAuthEnabled>sur "true". - Spécifiez la référence au Trustedstore à l'aide de l'élément
<TrustStore>. Le Truststore contient l'émetteur du certificat du client et la chaîne d'autorité de certification du certificat, ce qui est obligatoire.
Définir un hôte virtuel qui utilise le certificat et la clé d'essai sans frais Apigee
Si vous possédez un compte Edge for Cloud payant et que vous ne disposez pas encore d'un certificat et d'une clé TLS, vous pouvez créer un hôte virtuel qui utilise le certificat et la clé d'essai sans frais Apigee. Cela signifie que vous pouvez créer l'hôte virtuel sans créer de keystore au préalable.
Le certificat d'essai sans frais Apigee est défini pour le domaine *.apigee.net. Par conséquent, le <HostAlias> de l'hôte virtuel doit également être au format *.apigee.net.
Si vous utilisez une connexion TLS bidirectionnelle, vous devez toujours définir l'élément <ClientAuthEnabled> sur true et spécifier un magasin de confiance à l'aide d'une référence avec l'élément <TrustStore>, comme décrit ci-dessus dans la section Définir un hôte virtuel pour le protocole TLS bidirectionnel.
Un objet XML qui définit l'hôte virtuel à l'aide du certificat et de la clé d'essai sans frais Apigee omet les éléments <KeyStore> et <KeyAlias>, et les remplace par l'élément <UseBuiltInFreeTrialCert>, comme indiqué ci-dessous:
<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>
La valeur par défaut de l'élément <UseBuiltInFreeTrialCert> est "false".
Pour l'authentification TLS bidirectionnelle, définissez l'hôte virtuel comme suit:
<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>
Dans l'interface utilisateur Edge, sélectionnez l'option Utiliser un certificat d'essai sans frais intégré lors de la création de l'hôte virtuel pour utiliser le certificat et la clé Apigee sans frais:
Créer un hôte virtuel
Pour créer l'hôte virtuel, procédez comme suit:
- Créez une entrée DNS et un enregistrement CNAME pour votre domaine public (
api.myCompany.comdans cet exemple) qui pointe vers[org]-[environment].apigee.net. - Créez et configurez un keystore, nommé myTestKeystore dans cet exemple, en suivant la procédure décrite ici: Créer des keystores et un Truststore à l'aide de l'interface utilisateur Edge. Pour cet exemple, assurez-vous que le keystore utilise un nom d'alias myKeyAlias pour le certificat et la clé privée.
- Importez votre certificat et votre clé dans le keystore. Assurez-vous que le nom de domaine spécifié par votre certificat correspond à l'alias d'hôte que vous souhaitez utiliser pour l'hôte virtuel.
-
Créez une référence au keystore à l'aide de l'interface utilisateur ou de l'API Edge. La référence spécifie le nom du keystore et le type de référence en tant que
KeyStore. Consultez la section Utiliser des références pour en savoir plus sur la création et la modification de références. - Créez l'hôte virtuel à l'aide de l'API Créer un hôte virtuel. Veillez à spécifier la référence keystore et l'alias de clé corrects.
Pour utiliser l'API, utilisez l'appel d'API POST suivant pour créer le keystore nommé 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:passwordSi vous effectuez une exécution TLS bidirectionnelle avec le client, définissez
<ClientAuthEnabled>sur "true" et spécifiez le truststore à l'aide de l'élément<TrustStore>. Le client doit être correctement configuré pour le protocole TLS bidirectionnel, ce qui signifie qu'Edge dispose d'un Truststore contenant l'émetteur de certificat du client et la chaîne de certificats. Créez le Truststore en suivant la procédure décrite ici: Créer des keystores et un Truststore à l'aide de l'interface utilisateur Edge. Si vous disposez de proxys d'API existants, ajoutez l'hôte virtuel à l'élément
<HTTPConnection>du point de terminaison ProxyEndpoint. L'hôte virtuel est ajouté automatiquement à tous les nouveaux proxys d'API. Consultez la section Configurer un proxy d'API pour utiliser un hôte virtuel.
Après avoir mis à jour un proxy d'API pour utiliser l'hôte virtuel et créé l'entrée DNS et l'enregistrement CNAME pour l'alias d'hôte, vous pouvez accéder au proxy d'API comme indiqué ci-dessous:
https://api.myCompany.com/v1/{project-base-path}/{resource-path}
Exemple :
https://api.myCompany.com/v1/weather/forecastrss?w=12797282
Modifier un hôte virtuel
Les clients Cloud payants effectuent deux tâches principales pour modifier un hôte virtuel existant:
- Modification de la valeur d'une référence à un keystore ou à un Truststore.
Remarque: Une fois que vous avez défini une valeur<KeyStore>ou<TrustStore>pour utiliser une référence, vous pouvez la modifier à tout moment. Toutefois, si vous souhaitez modifier<KeyStore>ou<TrustStore>pour utiliser une référence différente, ou modifier<KeyAlias>pour utiliser un alias différent, vous devez contacter l'assistance Apigee Edge. - Modifier les propriétés TLS de l'hôte virtuel
Modifier la valeur d'une référence
Vous pouvez modifier la valeur d'une référence pour changer le keystore ou le truststore utilisé par un hôte virtuel.
Avant de modifier la valeur de la référence:
- Créez un keystore et importez un certificat et une clé, comme décrit dans la section Créer des keystores et des truststores à l'aide de l'interface utilisateur Edge. Dans le nouveau keystore, assurez-vous d'utiliser pour l'alias de clé le même nom que celui utilisé dans le magasin de clés existant.
- Si nécessaire, créez un nouveau Truststore et téléchargez un certificat comme décrit dans Créer des keystores et un Truststore à l'aide de l'interface utilisateur Edge.
- Modifiez la référence comme décrit dans la section Utiliser des références.
Modifier les propriétés TLS de l'hôte virtuel
Les clients payants peuvent utiliser l'API Mettre à jour un hôte virtuel pour mettre à jour un hôte virtuel. Cette API vous permet de définir toutes les propriétés de l'hôte virtuel décrites dans la documentation de référence sur les propriétés d'hôte virtuel.
Lorsque vous modifiez l'hôte virtuel, Edge effectue une validation semblable à la création d'un hôte virtuel. En d'autres termes, lors d'une modification, Edge vérifie que:
- Le domaine spécifié par l'alias d'hôte n'est utilisé dans aucune autre organisation ni aucun autre environnement.
- Vous êtes propriétaire du nom de domaine. Plus précisément, Edge vérifie que les informations suivantes dans le certificat correspondent à l'alias d'hôte :
- CN - Nom commun
- SAN : autre nom d'objet
- Edge vérifie que le certificat n'a pas expiré.
Pour modifier un hôte virtuel à l'aide de l'API Edge, procédez comme suit:
Mettez à jour l'hôte virtuel à l'aide de l'API Mettre à jour un hôte virtuel. Lorsque vous utilisez l'API, vous devez spécifier la définition complète de l'hôte virtuel dans le corps de la requête, et pas seulement les éléments que vous souhaitez modifier. Dans cet exemple, vous définissez la valeur de la propriété
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
Modifier un hôte virtuel pour utiliser des références au keystore et au truststore
Tous les nouveaux hôtes virtuels pour Edge dans le cloud utilisent une référence au keystore et au Trustedstore. Les références vous permettent de modifier le keystore et le truststore sans contacter l'assistance Apigee Edge.
Les hôtes virtuels plus anciens sur Apigee Edge risquent de ne pas être configurés pour utiliser des références pour les keystores et les Truststores. Dans ce cas, vous pouvez mettre à jour l'hôte virtuel pour qu'il utilise une référence.
Mettre à jour un hôte virtuel pour utiliser une référence
Pour mettre à jour l'hôte virtuel, procédez comme suit:
- Si nécessaire, créez un nouveau keystore et importez un certificat comme décrit dans la section Créer des keystores et des truststores à l'aide de l'interface utilisateur Edge. Si vous disposez déjà d'un keystore, vous pouvez configurer une référence pour qu'elle pointe vers celui-ci.
- Créez une référence au keystore.
- Si nécessaire, créez un nouveau Truststore et importez un certificat. Si vous disposez déjà d'un Truststore, vous pouvez configurer une référence pour qu'elle pointe vers celui-ci.
- Créez une référence au Trustedstore.
- Mettez à jour l'hôte virtuel pour définir le keystore, l'alias, le magasin de confiance et toute autre propriété TLS. La charge utile de l'appel est la suivante :
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 - Contactez l'assistance Apigee pour redémarrer les routeurs périphériques afin de terminer le processus.