Vous consultez la documentation Apigee Edge.
Accédez à la
documentation**Apigee X**. info
Un proxy d'API fonctionne comme un mappage d'un point de terminaison accessible au public à votre service de backend. Un hôte virtuel définit la manière dont le proxy d'API public est exposé à une application. Par exemple, l'hôte virtuel détermine si le proxy d'API est accessible à l'aide du protocole TLS. Lorsque vous configurez un proxy d'API, modifiez sa définition ProxyEndpoint pour configurer les hôtes virtuels qu'il utilise.
Le TargetEndpoint est l'équivalent sortant du ProxyEndpoint. Un TargetEndpoint fonctionne comme un client HTTP d'Edge vers un service de backend. Lorsque vous créez un proxy d'API, vous pouvez le configurer pour qu'il utilise zéro ou plusieurs TargetEndpoints.
En savoir plus :
- À propos de TLS/SSL
- Utiliser TLS avec Edge
- À propos des hôtes virtuels
- Keystores et truststores
- Documentation de référence sur la configuration des proxys d'API
Configurer un TargetEndpoint ou TargetServer
Pour configurer un TargetEndpoint, modifiez l'objet XML qui le définit. Vous pouvez modifier le TargetEndpoint en modifiant le fichier XML qui le définit dans votre proxy d'API, ou en le modifiant dans l'interface utilisateur de gestion Edge.
Pour modifier le TargetEndpoint à l'aide de l'interface utilisateur de gestion Edge :
- Connectez-vous à l'interface utilisateur de gestion Edge à l'adresse https://enterprise.apigee.com.
- Sélectionnez le nom du proxy d'API à mettre à jour.
- Sélectionnez l'onglet Développer.
- Sous Points de terminaison cibles, sélectionnez default.
- Dans la zone de code, la définition TargetEndpoint s'affiche, comme ci-dessous :
<TargetEndpoint name="default"> <Description/> <FaultRules/> <Flows/> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <Properties/> <SSLInfo> <Enabled>true</Enabled> <TrustStore>ref://myTrustStoreRef</TrustStore> </SSLInfo> <URL>https://mocktarget.apigee.net</URL> </HTTPTargetConnection> </TargetEndpoint> - Configurez un truststore comme décrit ci-dessous dans À propos de la configuration TLS avec le backend.
- Apportez les modifications nécessaires et enregistrez le proxy. Si le proxy d'API a été déployé, son enregistrement le redéploie avec le nouveau paramètre.
Notez que la définition TargetEndpoint contient une propriété name. Vous utilisez la valeur de
la name propriété
pour configurer la définition ProxyEndpoint d'un proxy d'API afin qu'il utilise le
TargetEndpoint.
Pour en savoir plus, consultez la documentation de référence sur la configuration des proxys d'API .
Les TargetEndpoints peuvent être configurés pour référencer un TargetServer, plutôt que l'URL cible explicite. Une configuration TargetServer dissocie les URL de point de terminaison concrètes des configurations TargetEndpoint. Les TargetServers sont utilisés pour assurer l'équilibrage de charge et le basculement sur plusieurs instances de serveur backend.
Vous trouverez ci-dessous un exemple de définition TargetServer :
<TargetServer name="target1"> <Host>mocktarget.apigee.net</Host> <Port>80</Port> <IsEnabled>true</IsEnabled> </TargetServer>
Un TargetServer est référencé par son nom dans l'élément <HTTPTargetConnection>
d'une définition TargetEndpoint.
Vous pouvez configurer un ou plusieurs TargetServers nommés, comme illustré ci-dessous.
<TargetEndpoint name="default">
...
<HTTPTargetConnection>
<LoadBalancer>
<Server name="target1" />
<Server name="target2" />
</LoadBalancer>
<Path>/test</Path>
</HTTPTargetConnection>
...
</TargetEndpoint>Pour en savoir plus, consultez la section Équilibrage de charge sur les serveurs de backend.
À propos de la configuration TLS avec le backend
Avant de configurer l'accès TLS au backend, vous devez comprendre deux points importants :
- Par défaut, Edge ne valide pas le certificat de backend. Vous devez créer un truststore pour configurer Edge afin qu'il valide le certificat.
- Utilisez une référence pour spécifier le keystore ou le truststore utilisé par Edge.
Les deux considérations sont décrites ci-dessous.
Définir un truststore pour activer la validation des certificats
Lorsque vous effectuez une requête TLS via un TargetEndpoint ou un TargetServer, Edge ne valide pas par défaut le certificat TLS reçu du serveur backend. Cela signifie qu'Edge ne valide pas les éléments suivants :
- Le certificat a été signé par une autorité de certification de confiance.
- Le certificat n'a pas expiré.
- Le certificat présente un nom commun. S'il existe un nom commun, Edge ne valide pas qu'il correspond au nom d'hôte spécifié dans l'URL.
Pour configurer Edge afin qu'il valide le certificat de backend, vous devez procéder comme suit :
- Créez un truststore sur Edge.
- Importez le certificat ou la chaîne de certificats du serveur dans le truststore. Si le certificat du serveur est signé par un tiers, vous devrez importer la chaîne de certificats complète, y compris le certificat de l'autorité de certification racine, dans le truststore. Il n'existe aucune autorité de certification implicitement approuvée.
- Ajoutez le truststore à la définition TargetEndpoint ou TargetServer.
Pour en savoir plus, consultez la section Keystores et truststores.
Exemple :
<TargetEndpoint name="default">
…
<HTTPTargetConnection>
<SSLInfo>
<Enabled>true</Enabled>
<TrustStore>ref://myTrustStoreRef</TrustStore>
</SSLInfo>
<URL>https://myservice.com</URL>
</HTTPTargetConnection>
…
</TargetEndpoint>Utiliser une référence à un keystore ou à un truststore
L'exemple ci-dessous montre comment configurer un TargetEndpoint ou un TargetServer pour qu'il soit compatible avec TLS. Lors de la configuration de TLS, vous spécifiez un truststore et un keystore dans le cadre d'une définition TargetEndpoint ou TargetServer.
Apigee vous recommande vivement d'utiliser une référence au keystore et au truststore dans la définition TargetEndpoints ou TargetServer. L'avantage d'utiliser une référence est que vous n'avez qu'à la mettre à jour pour qu'elle pointe vers un autre keystore ou truststore afin de mettre à jour le certificat TLS.
Les références aux keystores et aux truststores dans la définition TargetEndpoints ou TargetServer fonctionnent de la même manière que pour les hôtes virtuels.
Convertir un TargetEndpoint ou un TargetServer pour qu'il utilise une référence
Il est possible que vous disposiez de définitions TargetEndpoint ou TargetServer existantes qui utilisent le nom littéral du keystore et du truststore. Pour convertir la définition TargetEndpoint ou TargetServer afin qu'elle utilise des références :
- Mettez à jour la définition TargetEndpoint ou TargetServer pour qu'elle utilise une référence.
- Redémarrez les processeurs de messages Edge :
- Pour les clients Cloud public, contactez l'assistance Apigee Edge pour redémarrer les processeurs de messages.
- Pour les clients Cloud privé, redémarrez les processeurs de messages Edge un par un.
- Vérifiez que votre TargetEndpoint ou TargetServer fonctionne correctement.
Configurer une connexion TLS unidirectionnelle au serveur backend
Lorsque vous utilisez une définition TargetEndpoint, la configuration d'un accès TLS unidirectionnel d'Edge (client TLS) au serveur backend (serveur TLS) ne nécessite aucune configuration supplémentaire sur Edge. Il incombe au serveur backend de configurer correctement TLS.
Vous devez uniquement vous assurer que l'élément <URL> de la définition
TargetEndpoint référence le service de backend par le protocole HTTPS et que vous
activez TLS :
<TargetEndpoint name="default">
…
<HTTPTargetConnection>
<SSLInfo>
<Enabled>true</Enabled>
</SSLInfo>
<URL>https://myservice.com</URL>
</HTTPTargetConnection>
…
</TargetEndpoint>Si vous utilisez un TargetServer pour définir le service de backend, activez TLS dans la définition TargetServer :
<TargetServer name="target1">
<Host>mocktarget.apigee.net</Host>
<Port>443</Port>
<IsEnabled>true</IsEnabled>
<SSLInfo>
<Enabled>true</Enabled>
</SSLInfo>
</TargetServer> Toutefois, si vous souhaitez qu'Edge valide le certificat de backend, vous devez créer un truststore contenant le certificat ou la chaîne de certificats de backend. Vous spécifiez ensuite le truststore dans la définition TargetEndpoint :
<TargetEndpoint name="default">
…
<HTTPTargetConnection>
<SSLInfo>
<Enabled>true</Enabled>
<TrustStore>ref://myTrustStoreRef</TrustStore>
</SSLInfo>
<URL>https://myservice.com</URL>
</HTTPTargetConnection>
…
</TargetEndpoint>Ou dans la définition TargetServer :
<TargetServer name="target1">
<Host>mockserver.apigee.net</Host>
<Port>443</Port>
<IsEnabled>true</IsEnabled>
<SSLInfo>
<Enabled>true</Enabled>
<TrustStore>ref://myTrustStoreRef</TrustStore>
</SSLInfo>
</TargetServer>Pour configurer une connexion TLS unidirectionnelle :
- Si vous souhaitez valider le certificat de backend, créez un truststore sur Edge et importez le certificat de backend ou la chaîne d'autorités de certification, comme décrit dans Keystores et truststores. Dans cet exemple, si vous devez créer un truststore, nommez-le myTrustStore.
-
Si vous avez créé un truststore, utilisez l'appel d'API POST suivant pour créer la référence nommée myTrustStoreRef au truststore que vous avez créé ci-dessus :
curl -X POST -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \ -d '<ResourceReference name="myTrustStoreRef"> <Refers>myTrustKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>' -u email:password - Utilisez l'interface utilisateur de gestion Edge pour mettre à jour la définition TargetEndpoint du proxy d'API (ou,
si vous définissez le proxy d'API en XML, modifiez les fichiers XML du proxy) :
- Connectez-vous à l'interface utilisateur de gestion Edge à l'adresse https://enterprise.apigee.com.
- Dans le menu de l'interface utilisateur de gestion Edge, sélectionnez API.
- Sélectionnez le nom du proxy d'API à mettre à jour.
- Sélectionnez l'onglet Développement.
- Sous Points de terminaison cibles, sélectionnez default.
- Dans la zone de code, modifiez l'élément
<HTTPTargetConnection>pour ajouter l'élément<SSLInfo>. Veillez à spécifier la référence de truststore correcte et à définir<Enabled>sur "true" :<TargetEndpoint name="default"> … <HTTPTargetConnection> <SSLInfo> <Enabled>true</Enabled> <TrustStore>ref://myTrustStoreRef</TrustStore> </SSLInfo> <URL>https://myservice.com</URL> </HTTPTargetConnection> … </TargetEndpoint> - Enregistrez le proxy d'API. Si le proxy d'API a été déployé, son enregistrement le redéploie avec le nouveau paramètre.
Configurer une connexion TLS bidirectionnelle au serveur backend
Si vous souhaitez prendre en charge le protocole TLS bidirectionnel entre Edge (client TLS) et le serveur backend (serveur TLS) :
- Créez un keystore sur Edge et importez le certificat et la clé privée Edge.
- Si vous souhaitez valider le certificat de backend, créez un truststore sur Edge contenant le certificat et la chaîne d'autorités de certification que vous avez reçus du serveur backend.
- Mettez à jour le TargetEndpoint de tous les proxys d'API qui référencent le serveur backend pour configurer TLS access.
Utiliser l'alias de clé pour spécifier le certificat du keystore
Vous pouvez définir plusieurs certificats, chacun avec son propre alias, dans le même keystore. Par défaut, Edge utilise le premier certificat défini dans le keystore.
Vous pouvez également configurer Edge pour qu'il utilise le certificat spécifié par la propriété <KeyAlias>.
Cela vous permet de définir un seul keystore pour plusieurs certificats, puis
de sélectionner celui que vous souhaitez utiliser dans la définition TargetServer. Si Edge ne trouve pas de certificat avec un alias
correspondant à <KeyAlias>, il utilise l'action par défaut qui consiste à sélectionner le
premier certificat du keystore.
Les utilisateurs d'Edge pour le cloud public doivent contacter l'assistance Apigee Edge pour activer cette fonctionnalité.
Configurer une connexion TLS bidirectionnelle
Pour configurer une connexion TLS bidirectionnelle :
- Créez le keystore sur Edge et importez le certificat et la clé privée en suivant la procédure décrite dans Keystores et truststores. Dans cet exemple, créez un keystore nommé myTestKeystore qui utilise un alias myKey pour le certificat et la clé privée.
-
Utilisez l'appel d'API POST suivant pour créer la référence nommée myKeyStoreRef au keystore que vous avez créé ci-dessus :
curl -X POST -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \ -d '<ResourceReference name="myKeyStoreRef"> <Refers>myTestKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>' -u email:passwordLa référence spécifie le nom du keystore et le type de référence en tant que
KeyStore.Utilisez l'appel d'API GET suivant pour afficher la référence :
curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/myKeyStoreRef / -u email:password - Si vous souhaitez valider le certificat de backend, créez un truststore sur Edge et importez le certificat et la chaîne d'autorités de certification , comme décrit dans Keystores et truststores. Dans cet exemple, si vous devez créer un truststore, nommez-le myTrustStore.
-
Si vous avez créé un truststore, utilisez l'appel d'API POST suivant pour créer la référence nommée myTrustStoreRef au truststore que vous avez créé ci-dessus :
curl -X POST -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \ -d '<ResourceReference name="myTrustStoreRef"> <Refers>myTrustKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>' -u email:password - Utilisez l'interface utilisateur de gestion Edge pour mettre à jour la définition TargetEndpoint du proxy d'API (ou,
si vous définissez le proxy d'API en XML, modifiez les fichiers XML du proxy) :
- Connectez-vous à l'interface utilisateur de gestion Edge à l'adresse https://enterprise.apigee.com.
- Dans le menu de l'interface utilisateur de gestion Edge, sélectionnez API.
- Sélectionnez le nom du proxy d'API à mettre à jour.
- Sélectionnez l'onglet Développement.
- Sous Points de terminaison cibles, sélectionnez default.
- Dans la zone de code, modifiez l'élément
<HTTPTargetConnection>pour ajouter l'élément<SSLInfo>. Veillez à spécifier le keystore et l'alias de clé corrects, et à définir les éléments<Enabled>et<ClientAuthEnabled>sur "true" :<TargetEndpoint name="default"> ... <HTTPTargetConnection> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>ref://myKeyStoreRef</KeyStore> <KeyAlias>myKey</KeyAlias> </SSLInfo> <URL>https://myservice.com</URL> </HTTPTargetConnection> ... </TargetEndpoint> - Enregistrez le proxy d'API. Si le proxy d'API a été déployé, son enregistrement le redéploie avec le nouveau paramètre.
Pour en savoir plus sur les options disponibles dans le <TargetEndpoint>, y compris sur l'utilisation de variables
pour fournir des valeurs TargetEndpoint <SSLInfo>, consultez la documentation de référence sur la configuration des proxys d'API.
Activer SNI
Edge est compatible avec l'utilisation de l'indication du nom du serveur (SNI) à partir des processeurs de messages vers les points de terminaison cibles dans Apigee Edge pour le cloud et pour les déploiements de cloud privé.
Pour Edge pour le cloud privé, afin d'assurer la rétrocompatibilité avec vos backends cibles existants, Apigee a désactivé SNI par défaut. Si votre backend cible est configuré pour prendre en charge SNI, vous pouvez activer cette fonctionnalité. Pour en savoir plus, consultez la section Utiliser SNI avec Edge.