Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info
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ôte virtuel 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é autorisé à modifier un hôte virtuel. Les utilisateurs appartenant à d'autres rôles ne sont pas autorisés à créer des hôtes virtuels.
Par exemple, les clients payants peuvent:
- Activer TLS unidirectionnelle et bidirectionnelle
- 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 d'Edge. Pour en savoir plus sur les forfaits Edge, consultez la page https://apigee.com/api-management/#/pricing.
Conditions requises pour configurer un hôte virtuel pour le cloud
Le tableau suivant récapitule les exigences 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 d'hôtes virtuels. |
| Rôle utilisateur | administrateur de l'organisation | Seul un administrateur de l'entreprise peut créer un hôte virtuel ou un utilisateur doté d'un rôle personnalisé autorisé à modifier un hôte virtuel. |
| Nombre d'hôtes virtuels | 20 maximum |
Vous êtes limité à 20 hôtes virtuels maximum 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 l'accès HTTP et un pour l'accès HTTPS. Vous devrez peut-être ajouter des hôtes virtuels si votre organisation/environnement autorise l'accès à l'aide de différents noms de domaine. |
| URL de base | Inclut le protocole | Lorsque vous définissez l'URL de base de l'hôte virtuel, dans l'UI 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 aient 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 déjà avoir créé un keystore et éventuellement un truststore contenant votre certificat et votre 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 la version 1.2 de TLS. |
| Alias d'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 détenir le 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é. |
| Prise en charge de l'extension SNI de l'application cliente | Toutes les applications clientes accédant à l'hôte virtuel doivent être compatibles avec l'extension SNI. |
La prise en charge de la SNI est obligatoire 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 > Virtual Hosts (Administration > 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.
- Pour en savoir plus sur le remplissage des champs d'hôte virtuel, consultez le tableau ci-dessus.
Définir un hôte virtuel pour le 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 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:
- Spécifiez myTLSVHost comme nom. 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.
- Spécifiez le numéro de port 443. Si aucune valeur n'est spécifiée, le port est défini sur 443 par défaut.
- Activez TLS si nécessaire.
L'élément<Enable>est défini sur "true" pour activer le protocole TLS unidirectionnel, 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 truststore à 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, qui est obligatoire.
Remarque:Étant donné qu'Edge était initialement compatible avec SSL, la balise que vous utilisez pour configurer TLS est nommée<SSLInfo>.
Notez que vous pouvez définir d'autres propriétés dans l'hôte virtuel. Pour obtenir une référence de toutes les propriétés, consultez la documentation de référence sur les propriétés de l'hôte virtuel.
Décider comment spécifier le keystore et le nom 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 contenant le nom du keystore ou du truststore, plutôt que de spécifier directement le nom du keystore ou du truststore, comme illustré 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 la valeur de la référence afin de changer le keystore utilisé par l'hôte virtuel, généralement en cas d'expiration prochaine du certificat du keystore actuel. Modifier la valeur de la référence ne vous oblige pas à redémarrer le routeur Edge. Pour en savoir plus sur la création et la modification de références, consultez la page 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 des références aux keystores et au truststore
Vous devez tenir compte de la restriction suivante lorsque vous utilisez des références à des keystores et à des truststores:
- Vous ne pouvez utiliser des références keystore et truststore dans des hôtes virtuels que si vous acceptez SNI et que vous arrêtez le protocole SSL sur les routeurs Apigee.
- Si vous avez 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 truststore 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 truststore à 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, qui est obligatoire. Le client doit également être correctement configuré pour le protocole TLS bidirectionnel.
Pour créer un hôte virtuel pour TLS à deux voies, 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 truststore à 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, qui est obligatoire.
Définir un hôte virtuel qui utilise le certificat et la clé d'essai sans frais d'Apigee
Si vous disposez d'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 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 Apigee est défini pour un 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 exécutez un protocole TLS bidirectionnel, vous devez toujours définir l'élément <ClientAuthEnabled> sur true et spécifier un truststore 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 du certificat et de la clé 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 TLS à deux voies, 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 Use built-in free trial certificate (Utiliser le certificat d'essai sans frais intégré) lorsque vous créez 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 dans Créer des keystores et des truststores à l'aide de l'UI Edge. Pour cet exemple, assurez-vous que le keystore utilise un nom d'alias myKeyAlias pour le certificat et la clé privée.
- Importez le certificat et la 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 comme
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 Créer un hôte virtuel. Veillez à spécifier la référence et l'alias de clé du keystore appropriés.
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 exécutez un protocole TLS bidirectionnel 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 TLS bidirectionnel, ce qui signifie qu'Edge dispose d'un truststore contenant l'émetteur et la chaîne de certificats du client. Créez le truststore en suivant la procédure décrite dans Créer des keystores et des truststores à l'aide de l'interface utilisateur Edge. Si vous disposez de proxys d'API existants, ajoutez l'hôte virtuel à l'élément
<HTTPConnection>dans ProxyEndpoint. L'hôte virtuel est ajouté automatiquement à tous les nouveaux proxys d'API. Consultez la section Configurer un proxy d'API pour qu'il utilise un hôte virtuel.
Après avoir mis à jour un proxy d'API pour qu'il utilise 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:
- Modifier la valeur d'une référence à un keystore ou à un truststore.
Remarque: Une fois que vous avez défini un<KeyStore>ou un<TrustStore>pour utiliser une référence, vous pouvez modifier la valeur de la référence à tout moment. Toutefois, si vous souhaitez modifier<KeyStore>ou<TrustStore>pour utiliser une autre référence, 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 modifier 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, puis importez un certificat et une clé comme décrit dans la section Créer des keystores et des truststores à l'aide de l'UI 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 truststore et importez un certificat comme décrit dans la section Créer des keystores et des truststores à l'aide de l'UI 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 Modifier 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 section Documentation de référence des propriétés de l'hôte virtuel.
Lorsque vous modifiez l'hôte virtuel, Edge effectue une validation semblable à celle que vous effectuez lorsque vous créez un hôte virtuel. Autrement dit, lors d'une modification, Edge vérifie que:
- Le domaine spécifié par l'alias d'hôte n'est pas utilisé dans une autre organisation et dans un autre environnement.
- Vous possédez le nom de domaine. Plus précisément, Edge vérifie que les informations suivantes du certificat correspondent à l'alias d'hôte :
- CN : nom commun
- SAN (Subject Alternative Name)
- 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 qu'il utilise 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 truststore. Les références vous permettent de modifier le keystore et le truststore sans avoir à contacter l'assistance Apigee Edge.
Les hôtes virtuels plus anciens sur Apigee Edge ne sont peut-être pas configurés pour utiliser des références pour des keystores et des 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 qu'il utilise une référence
Pour mettre à jour l'hôte virtuel, procédez comme suit:
- Si nécessaire, créez un keystore et importez un certificat comme décrit dans la section Créer des keystores et des truststores à l'aide de l'UI Edge. Si vous disposez déjà d'un keystore, vous pouvez configurer une référence pour y accéder.
- Créez une référence au keystore.
- Si nécessaire, créez un truststore et importez un certificat. Si vous disposez déjà d'un truststore, vous pouvez configurer une référence pour y faire référence.
- Créez une référence au truststore.
- Mettez à jour l'hôte virtuel pour définir le keystore, l'alias, le truststore et toute autre propriété TLS. La charge utile pour 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 Edge et finaliser le processus.