Vous consultez la documentation sur Apigee Edge.
Consultez la documentation sur Apigee X.
Un client Cloud disposant d'un compte payant peut créer un hôte virtuel dans une organisation.
En savoir plus :
Qui peut créer et modifier des hôtes virtuels dans le cloud ?
La création et la modification d'hôtes virtuels ne sont disponibles que pour les comptes payants 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é autorisé à modifier un hôte virtuel. Les utilisateurs avec d'autres rôles ne sont pas autorisés à créer des hôtes virtuels.
Par exemple, les clients payants peuvent:
- Activer le TLS unidirectionnel
- Spécifier le keystore ou le magasin de confiance utilisé par l'hôte virtuel
Les comptes d'essai et sans frais 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 en savoir plus sur les forfaits Edge, consultez https://apigee.com/api-management/#/pricing.
Conditions requises pour configurer un hôte virtuel pour Cloud
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 permettent pas de créer ni de modifier des hôtes virtuels. |
| Rôle d'utilisateur | administrateur de l'organisation | Seul un administrateur de l'entreprise peut créer un hôte virtuel, ou un utilisateur dont le rôle personnalisé est autorisé à modifier un hôte virtuel. |
| Nombre d'hôtes virtuels | 20 |
Vous êtes limité à 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 pouvez avoir besoin d'hôtes virtuels supplémentaires si votre organisation/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, dans l'interface utilisateur ou avec 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 disposent d'alias d'hôte uniques et que tous les ports suivants soient compatibles avec le protocole TLS. |
| TLS | Obligatoire |
Vous ne pouvez créer qu'un hôte virtuel compatible avec TLS sur HTTPS. Vous devez avoir créé un keystore, et éventuellement un keystore contenant le certificat et la clé TLS. Vous devez disposer d'un certificat 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 TLS 1.2. |
| Alias d'hôte | Unique dans l'organisation et dans l'environnement | L'alias d'hôte n'existe pas pour une autre combinaison organisation/environnement. |
| Nom de domaine | Propriété du 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 réseau SAN ou le CN, par exemple Edge vérifie également que le certificat n'a pas expiré. |
| Compatibilité avec l'extension SNI de l'application cliente | Toutes les applications clientes accédant à l'hôte virtuel doivent être compatibles avec la SNI. |
La compatibilité avec l'extension SNI est requise pour 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 > 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 son nom pour le modifier.
- Pour en savoir plus sur le remplissage des champs de l'hôte virtuel, consultez le tableau ci-dessus.
Définir un hôte virtuel pour le protocole TLS à sens unique
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 à sens unique:
<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, vous:
- Dans name (nom), saisissez myTLSVHost. Utilisez ce nom pour référencer l'hôte virtuel dans un proxy d'API ou dans un appel d'API.
- Définissez l'alias d'hôte sur api.myCompany.com. Il s'agit du domaine public utilisé pour accéder à vos API, tel que défini par un enregistrement DNS et une définition DNS.
- Spécifiez le numéro port comme 443. En cas d'omission, 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, tandis que les éléments<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 magasin de confiance contient l'émetteur du certificat du client et la chaîne d'autorités de certification du certificat.
Remarque:Comme Edge était à l'origine compatible avec SSL, le tag que vous utilisez pour configurer le protocole TLS s'appelle<SSLInfo>.
Notez que vous pouvez définir d'autres propriétés 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 des hôtes virtuels.
Choisir le nom du keystore et du magasin de confiance dans l'hôte virtuel
Lorsque vous configurez un hôte virtuel 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 keystore au lieu de spécifier directement le nom du keystore ou du keystore, comme indiqué ci-dessous:
<SSLInfo>
<Enabled>true</Enabled>
<ClientAuthEnabled>false</ClientAuthEnabled>
<KeyStore>ref://myTestKeystoreRef</KeyStore>
<KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>
L'avantage d'une référence est que vous pouvez modifier sa valeur pour changer le keystore utilisé par l'hôte virtuel, généralement parce que le certificat du keystore actuel expire bientôt. La modification de la valeur de la référence ne nécessite pas de redémarrer le routeur périphérique. Pour en savoir plus sur la création et la modification de références, consultez Utiliser des 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 liées à l'utilisation de références aux keystores et au keystore
Vous devez prendre en compte la restriction suivante lorsque vous utilisez des références à des keystores et des keystores:
- Vous ne pouvez utiliser des références keystore et Filestore de confiance dans les hôtes virtuels que si vous prenez en charge l'extension SNI et si 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 arrêtez le protocole TLS sur l'équilibreur de charge, vous ne pouvez pas utiliser de références keystore et Filestore 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, puis spécifiez un magasin de confiance en utilisant une référence avec l'élément <TrustStore>. Le magasin de confiance contient l'émetteur du certificat du client et la chaîne d'autorités de certification du certificat. 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, vous:
- Activez le protocole TLS bidirectionnel en définissant
<ClientAuthEnabled>sur "true". - Spécifiez la référence au magasin de confiance à l'aide de l'élément
<TrustStore>. Le magasin de confiance contient l'émetteur du certificat du client et la chaîne d'autorités de certification du certificat.
Définir un hôte virtuel utilisant le certificat et la clé d'essai sans frais d'Apigee
Si vous possédez un compte Edge for Cloud payant et que vous n'avez pas encore de certificat et de clé TLS, vous pouvez créer un hôte virtuel qui utilise le certificat et la clé d'essai sans frais d'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 d'Apigee est défini pour le domaine *.apigee.net. Par conséquent, le <HostAlias> de l'hôte virtuel doit également se présenter sous la forme *.apigee.net.
Si vous effectuez un chiffrement TLS bidirectionnel, vous devez toujours définir l'élément <ClientAuthEnabled> sur true et spécifier un magasin de confiance en utilisant 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 de la clé et du certificat d'essai sans frais d'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 le protocole TLS bidirectionnel, 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 le certificat de l'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
Procédez comme suit pour créer l'hôte virtuel:
- Créez une entrée DNS et un enregistrement CNAME pour votre domaine public,
api.myCompany.compour 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 keystore à l'aide de l'interface utilisateur Edge. Pour cet exemple, assurez-vous que le keystore utilise le 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
KeyStore. Pour en savoir plus sur la création et la modification de références, consultez Utiliser des références. - Créez l'hôte virtuel à l'aide de l'API Create a Virtual Host (Créer un hôte virtuel). Veillez à spécifier le bon keystore et l'alias de clé.
Pour utiliser l'API, créez le keystore nommé myTLSVHost à l'aide de l'appel d'API POST suivant :
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 un contrôle TLS bidirectionnel avec le client, définissez
<ClientAuthEnabled>sur "true" et spécifiez le magasin de confiance à 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 magasin de confiance contenant l'émetteur et la chaîne de certificats du client. Créez le keystore en suivant la procédure décrite ici: Créer des keystores et un magasin de confiance à l'aide de l'interface utilisateur Edge. Si vous disposez déjà de proxys d'API, ajoutez l'hôte virtuel à l'élément
<HTTPConnection>du proxy. L'hôte virtuel est ajouté automatiquement à tous les nouveaux proxys d'API. Consultez 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 effectuent deux tâches principales pour modifier un hôte virtuel existant:
- Modifier la valeur d'une référence à un keystore ou à un keystore
Remarque: Une fois que vous avez défini une valeur<KeyStore>ou<TrustStore>pour utiliser une référence, vous pouvez modifier sa valeur à tout moment. Toutefois, si vous souhaitez modifier<KeyStore>ou<TrustStore>pour utiliser une référence différente, ou modifier<KeyAlias>pour utiliser un autre alias, 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 keystore 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 Créer des keystores et un keystore à l'aide de l'interface utilisateur Edge. Dans le nouveau keystore, assurez-vous d'utiliser le même nom pour l'alias de clé que celui du keystore existant.
- Si nécessaire, créez un magasin de confiance et importez un certificat comme décrit dans la section Créer des keystores et un magasin de confiance à 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 de l'hôte virtuel.
Lorsque vous modifiez l'hôte virtuel, Edge effectue une validation semblable à la création d'un hôte virtuel. Autrement dit, en cas de 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 le propriétaire du nom de domaine. Plus précisément, Edge vérifie que les informations suivantes du certificat correspondent à l'alias de l'hôte :
- CN - Nom commun
- SAN – Autre nom de l'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 Update a Virtual Host (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 keystore
Tous les nouveaux hôtes virtuels pour Edge dans le cloud utilisent des références au keystore et au keystore. Les références vous permettent de modifier le keystore et le keystore sans contacter l'assistance Apigee Edge.
Les hôtes virtuels plus anciens sur Apigee Edge peuvent ne pas être configurés pour utiliser des références pour les keystores et les keystores. 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:
- Si nécessaire, créez un keystore et importez un certificat, comme décrit dans Créer des keystores et un keystore à l'aide de l'interface utilisateur Edge. Si vous avez déjà un keystore, vous pouvez configurer une référence pour y pointer.
- Créez une référence au keystore.
- Si nécessaire, créez un magasin de confiance et importez un certificat. Si vous avez déjà un magasin de confiance, vous pouvez configurer une référence pour y pointer.
- Créez une référence au magasin de confiance.
- Mettez à jour l'hôte virtuel pour définir le keystore, l'alias, le keystore et toutes les autres propriétés TLS. La charge utile de l'appel est :
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 Edge afin de terminer le processus.