Options de configuration de TLS

Vous consultez la documentation Apigee Edge.
Accéder à la documentation d'Apigee X
en savoir plus

Ce document vous propose un aperçu de la configuration de TLS sur Edge pour deux domaines d'activité :

  1. Accédez à vos proxys d'API par des clients API. Utilisez des hôtes virtuels sur le routeur Edge pour configurer TLS.
  2. Accédez à vos services de backend par Edge. Utilisez des points de terminaison cibles et des serveurs cibles sur le processeur de messages Edge pour configurer TLS.

Ces deux types d'accès sont présentés ci-dessous :

À propos de la définition des options TLS dans un hôte virtuel ou un point de terminaison cible/serveur cible

Un hôte virtuel peut être représenté par un objet XML, au format suivant :

<VirtualHost name="secure">
    ...
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTruststoreRef</TrustStore> 
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

La zone de l'hôte virtuel que vous modifiez pour configurer TLS est définie par le tag <SSLInfo>. Utilisez le même tag <SSLInfo> pour configurer un point de terminaison cible ou un serveur cible.

Le tableau suivant décrit les éléments de configuration TLS utilisés par le tag <SSLInfo> :

Élément Description
<Enabled>

Active le protocole TLS unidirectionnel entre Edge et le client API, ou entre Edge et le backend cible.

Pour un hôte virtuel, vous devez définir un keystore contenant le certificat et la clé privée.

<ClientAuthEnabled>

Active le protocole TLS bidirectionnel entre Edge et le client API, ou entre Edge et le backend cible.

L'activation du protocole TLS bidirectionnel nécessite généralement que vous configuriez un magasin de confiance sur Edge.

<KeyStore> Keystore.
<KeyAlias> Alias spécifié lorsque vous avez importé un certificat et une clé privée dans le keystore.
<TrustStore> Truststore.
<IgnoreValidationErrors>

Si la valeur est "true", Edge ignore les erreurs de certificat TLS. Valide lors de la configuration de TLS pour les serveurs cibles et les points de terminaison cibles, ainsi que lors de la configuration d'hôtes virtuels utilisant le TLS bidirectionnel. La valeur par défaut est false.

Lorsqu'il est utilisé avec un point de terminaison cible ou un serveur cible, si le système backend utilise SNI et renvoie un certificat dont le nom distinctif (DN) de l'objet ne correspond pas au nom d'hôte, il est impossible d'ignorer l'erreur et la connexion échoue.

<CommonName>

Si spécifié, une valeur par rapport à laquelle le nom commun du certificat cible est validé. Cette valeur n'est valide que pour les configurations TargetEndpoint et TargetServer. Il n'est pas valide pour les configurations VirtualHost.

Par défaut, la valeur spécifiée correspond exactement au nom commun du certificat cible. Par exemple, utiliser *.myhost.com comme valeur pour <CommonName> fera correspondre et validera le nom d'hôte cible uniquement si la valeur exacte *.myhost.com est spécifiée comme nom commun dans le certificat cible.

Apigee peut éventuellement effectuer la correspondance avec des caractères génériques à l'aide de l'attribut wildcardMatch.

Par exemple, un nom commun spécifié comme abc.myhost.com dans un certificat cible serait mis en correspondance et validé si l'élément <CommonName> est spécifié comme suit :

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

À propos de la définition des éléments <KeyStore> et <TrustStore>

Dans l'exemple d'hôte virtuel ci-dessus, le keystore et le truststore sont spécifiés à l'aide de references sous la forme :

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

Apigee vous recommande vivement de toujours utiliser les références au keystore et au truststore. 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. Dans cet exemple :

  • myKeystoreRef est une référence contenant le nom du keystore. Dans cet exemple, le nom du keystore est myKeystore.
  • myTruststoreRef est une référence contenant le nom du truststore. Dans cet exemple, le nom du truststore est myTruststore.

Lorsqu'un certificat expire, vous devez mettre à jour l'hôte virtuel ou le point de terminaison cible/serveur cible pour spécifier le keystore ou le truststore contenant le nouveau certificat. L'avantage d'une référence est que vous pouvez modifier sa valeur pour modifier le keystore ou le truststore sans avoir à modifier l'hôte virtuel ou le point de terminaison cible/serveur cible lui-même :

  • Pour les clients Cloud: pour modifier la valeur de la référence, vous n'avez pas besoin de contacter l'assistance Apigee Edge.
  • Pour les clients cloud privé : Modifier la valeur de la référence ne vous oblige pas à redémarrer les composants Edge, tels que les routeurs et les processeurs de message.

Vous pouvez également spécifier directement le nom du keystore et le nom du truststore :

<KeyStore>myKeystore</KeyStore>
<TrustStore>myTruststore</TrustStore> 

Si vous spécifiez directement le nom du keystore ou du magasin de confiance, les clients Cloud doivent contacter l'assistance Apigee Edge et les clients de Private Cloud doivent redémarrer certains composants Edge pour mettre à jour le certificat.

Une troisième option, pour les points de terminaison cibles/serveurs cibles uniquement, consiste à utiliser des variables de flux :

<KeyStore>{ssl.keystore}</KeyStore>
<TrustStore>{ssl.truststore}</TrustStore> 

Les variables de flux fonctionnent pour les points de terminaison cibles/serveurs cibles et vous permettent de mettre à jour le keystore ou le truststore comme les références. Cependant, ils ne fonctionnent pas avec les hôtes virtuels et vous obligent à transmettre des informations concernant le keystore, l'alias et le truststore à chaque requête.

Restrictions liées à l'utilisation des références aux keystores et au truststore

Les clients cloud payant, ainsi que tous les clients cloud privé en charge de la configuration TLS, doivent prendre en compte la restriction suivante lorsqu'ils utilisent des références aux keystores et truststores :

  • Vous ne pouvez utiliser des références keystore et truststore dans des hôtes virtuels que si vous interrompez le protocole TLS sur les routeurs Apigee.
  • Si vous disposez d'un équilibreur de charge devant les routeurs Apigee et que vous interrompez le protocole TLS sur l'équilibreur de charge, vous ne pouvez pas utiliser de références à des magasins de clés et des magasins de confiance dans les hôtes virtuels.

Si votre hôte virtuel existant utilise un nom de keystore ou de magasin de confiance littéral

Les hôtes virtuels existants sur Edge ne sont peut-être pas être 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.

  1. Edge pour le cloud

    Pour modifier l'hôte virtuel afin qu'il utilise une référence au keystore, vous devez faire appel à l'assistance Apigee Edge.

  2. Edge pour le cloud privé

    Pour convertir l'hôte virtuel afin d'utiliser une référence, procédez comme suit :

    1. Mettez à jour l'hôte virtuel pour utiliser une référence.
    2. Redémarrez les routeurs.
    Pour en savoir plus, consultez la section "Modifier un hôte virtuel pour utiliser des références au keystore et au magasin de clés de confiance" dans Configurer l'accès TLS à une API pour le cloud privé.

À propos de l'utilisation du certificat et de la clé d'essai sans frais Apigee

Si vous possédez un compte Edge for Cloud payant et que vous ne possédez pas encore de certificat ni de 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.

Un objet XML qui définit l'hôte virtuel à l'aide du certificat d'essai sans frais et de la clé 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>

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>.

Consultez la section Configurer des hôtes virtuels pour le cloud pour en savoir plus.

À propos de la configuration de TLS

Deux facteurs principaux déterminent la manière dont vous effectuez la configuration de TLS :

  • Êtes-vous un client cloud Edge ou cloud privé ?
  • Comment allez-vous mettre à jour les certificats expirés ou arrivant à expiration ?

Options de configuration du cloud et du cloud privé

Le tableau suivant présente les différentes options de configuration pour les clients cloud et cloud privé :

Private Cloud Cloud
Hôte virtuel Contrôle total Contrôle total pour les comptes payants uniquement
Point de terminaison cible/Serveur cible Contrôle total Contrôle total

Les clients de cloud privé ont un contrôle total sur la configuration des hôtes virtuels et des points de terminaison cibles/serveurs cibles. Ce contrôle inclut la possibilité de créer et de supprimer des hôtes virtuels, et permet également de définir toutes les propriétés d'un hôte virtuel.

Tous les clients cloud, qu'il s'agisse d'un compte payant ou d'évaluation, ont un contrôle total sur la configuration des points de terminaison cibles/serveurs cibles. En outre, les clients cloud payant ont un contrôle total sur les hôtes virtuels, y compris les propriétés TLS.

Gérer les certificats expirés

Si un certificat TLS expire, ou si la configuration de votre système change de sorte qu'il n'est plus valide, vous devez le mettre à jour. Lorsque vous configurez le protocole TLS pour un hôte virtuel ou un point de terminaison cible/serveur cible, vous devez décider du mode d'exécution de cette mise à jour avant d'effectuer toute configuration.

Lorsqu'un certificat arrive à expiration

Sur Edge, vous stockez les certificats à l'un des deux emplacements suivants :

  • Keystore : contient le certificat TLS et la clé privée utilisés pour identifier l'entité lors du handshake TLS.
  • Truststore : contient les certificats de confiance d'un client TLS utilisé pour valider le certificat d'un serveur TLS présenté au client. Ces certificats sont généralement des certificats autosignés, des certificats signés par une autorité de certification (CA) de confiance ou des certificats utilisés dans le cadre du protocole TLS bidirectionnel.

Lorsqu'un certificat d'un keystore expire et que vous utilisez une référence au keystore, vous ne pouvez pas importer de nouveau certificat dans le keystore. À la place, vous :

  1. Créez un nouveau keystore.
  2. Importez le nouveau certificat dans le nouveau keystore en utilisant le même nom d'alias que dans l'ancien keystore.
  3. Mettez à jour la référence dans votre hôte virtuel ou votre point de terminaison cible/serveur cible pour utiliser le nouveau keystore.

Lorsqu'un certificat dans un truststore arrive à expiration et que vous utilisez une référence au truststore, vous :

  1. Créez un nouveau truststore.
  2. Importez le nouveau certificat dans le nouveau truststore. Le nom d'alias n'a pas d'importance pour les truststores. Remarque : Si un certificat fait partie d'une chaîne, vous devez soit créer un fichier unique contenant tous les certificats et l'importer dans un seul alias, ou importer séparément tous les certificats de la chaîne dans le truststore à l'aide d'un alias différent pour chaque certificat.
  3. Mettez à jour la référence de votre hôte virtuel ou de votre serveur cible/point de terminaison cible afin d'utiliser le nouveau truststore.

Récapitulatif des méthodes de mise à jour d'un certificat expiré

La méthode que vous utilisez pour spécifier le nom du keystore et du truststore dans l'hôte virtuel ou le point de terminaison/serveur cible détermine la manière dont vous effectuez la mise à jour du certificat. Vous pouvez utiliser des :

  • Références
  • Noms directs
  • Variables de flux

Chacune de ces méthodes a des répercussions différentes sur le processus de mise à jour, comme décrit dans le tableau suivant. Comme vous pouvez le voir, les références constituent la plus grande flexibilité possible pour les clients cloud et cloud privé :

Type de configuration Comment mettre à jour/remplacer le certificat Private Cloud Cloud
Référence (recommandé) Pour un keystore, créez-en un avec un nouveau nom et un alias portant le même nom que l'ancien alias.

Pour un truststore, créez un truststore avec un nouveau nom.

Mettez à jour la référence au keystore ou au truststore.

Aucun redémarrage du routeur ou du processeur de messages n'est nécessaire.

Mettez à jour la référence au keystore ou au truststore.

Inutile de contacter l'Assistance Apigee.

Variables de flux (point de terminaison cible uniquement) Pour un keystore, créez un keystore avec un nouveau nom et un alias portant le même nom ou avec un nouveau nom.

Pour un truststore, créez un truststore avec un nouveau nom.

Transmettez la variable de flux mise à jour à chaque requête avec le nom du nouveau keystore, de l'alias ou du nouveau truststore.

Aucun redémarrage du routeur ou du processeur de messages n'est nécessaire.

Transmettez la variable de flux mise à jour à chaque requête avec le nom du nouveau keystore, de l'alias ou du nouveau truststore.

Inutile de contacter l'Assistance Apigee.

Accès direct Créez un nouveau keystore, un alias et un truststore. Mettez à jour l'hôte virtuel et redémarrez les routeurs.

Si le truststore est utilisé par un point de terminaison cible/serveur cible, redéployez le proxy.

Pour les hôtes virtuels, contactez l'assistance Apigee Edge pour redémarrer les routeurs.

Si le truststore est utilisé par un point de terminaison cible/serveur cible, redéployez le proxy.

Directe Supprimez le keystore ou le truststore et recréez-le avec le même nom. Aucune mise à jour de l'hôte virtuel n'est requise, aucun redémarrage du routeur n'est nécessaire. Toutefois, les requêtes API échouent jusqu'à ce que le nouveau keystore et l'alias soient définis.

Si le keystore est utilisé pour le protocole TLS bidirectionnel entre Edge et le service de backend, redémarrez les processeurs de messages.

Aucune mise à jour de l'hôte virtuel n'est requise. Toutefois, les requêtes API échouent jusqu'à ce que le nouveau keystore et l'alias soient définis.

Si le keystore est utilisé pour le TLS bidirectionnel entre Edge et le service de backend, contactez l'assistance Apigee Edge pour redémarrer les processeurs de messages.

Directe Pour le truststore uniquement, importez un nouveau certificat dans le truststore. Si le Truststore est utilisé par un hôte virtuel, redémarrez les routeurs.

Si le truststore est utilisé par un point de terminaison cible/serveur cible, redémarrez les processeurs de message.

Pour les hôtes virtuels, contactez l'assistance Apigee Edge afin de redémarrer les routeurs Edge.

Si le magasin de confiance est utilisé par un point de terminaison/serveur cible cible, contactez l'assistance Apigee Edge pour redémarrer les processeurs de messages.