Options de configuration de TLS

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Dans cette section, nous expliquons comment configurer TLS pour le trafic entre un proxy et une cible.

À propos de la définition des options TLS dans un point de terminaison cible ou un serveur cible

Une cible peut être représentée par un objet XML comme celui présenté ci-dessous :

<HTTPTargetConnection>
    <Properties/>
    <URL>https:myTargetAddress</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <Enforce>true</Enforce>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTruststoreRef</TrustStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <Protocols>myProtocols</Protocols>
        <Ciphers>myCipher</Ciphers>
    </SSLInfo>
</HTTPTargetConnection>

La zone de la configuration du point de terminaison cible que vous modifiez pour configurer TLS est définie par le tag <SSLInfo>. Vous utilisez le même tag <SSLInfo> pour configurer un point de terminaison cible ou un serveur cible.

Pour plus d'informations sur les éléments enfants de <SSLInfo>, consultez Configuration de TLS/SSL TargetEndpoint.

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

Élément Description
<Enabled> Le bloc <SSLInfo> peut être utilisé pour les protocoles TLS/SSL unidirectionnels et bidirectionnels.

Si la valeur est true, <Enabled> indique que le bloc <SSLInfo> doit être utilisé. Lorsque ce paramètre est défini sur false, le bloc <SSLInfo> est ignoré.

La valeur par défaut de <Enabled> est true si <URL> spécifie le protocole HTTPS et false si <URL> spécifie HTTP.
<Enforce>

Applique le protocole SSL strict entre Apigee et le backend cible.

Si la valeur est définie sur true, les connexions échouent pour les cibles avec des certificats non valides, des certificats expirés, des certificats autosignés, des certificats avec un nom d'hôte qui ne correspond pas et des certificats avec une racine non approuvée. Un code d'échec 4xx ou 5xx est renvoyé.

Si cette valeur n'est pas définie ou est définie sur false, le résultat des connexions aux backends cibles avec des certificats problématiques dépend du paramètre <IgnoreValidationErrors> (voir ci-dessous). Une réponse de réussite (2xx) peut se produire dans certaines conditions, si <IgnoreValidationErrors> est défini sur true.
<ClientAuthEnabled>

Active le protocole TLS bidirectionnel (également appelé TLS mutuel ou mTLS) entre Apigee et le client API, ou entre Apigee et le backend cible.

L'activation du TLS bidirectionnel nécessite généralement de configurer un truststore sur Apigee et un truststore.
<KeyStore> Keystore contenant des clés privées utilisées pour l'authentification du client sortant
<KeyAlias> Alias spécifié lorsque vous avez importé un certificat et une clé privée dans le keystore.
<TrustStore> Keystore contenant des certificats de serveur approuvés.
<IgnoreValidationErrors>

Indique si les erreurs de validation sont ignorées. 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.

Remarque : Si la valeur de <Enforce> est définie sur true, la valeur de <IgnoreValidationErrors> est ignorée.
<Ciphers>

Algorithmes de chiffrement compatibles avec le TLS/SSL sortant. Si aucun algorithme n'est spécifié, tous les algorithmes de chiffrement disponibles pour la JVM sont autorisés.

Pour limiter les algorithmes de chiffrement, ajoutez ces éléments qui listent les algorithmes de chiffrement acceptés :

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
<Protocols>

Protocoles compatibles pour le TLS/SSL sortant. Si aucun protocole n'est spécifié, tous les protocoles disponibles pour la JVM seront autorisés.

Pour limiter les protocoles, spécifiez-les explicitement. Par exemple, pour n'autoriser que TLS v1.2 ou TLS v1.3 :

<Protocols>
 <Protocol>TLSv1.2</Protocol>
 <Protocol>TLSv1.3</Protocol>
</Protocols>

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

Dans l'exemple ci-dessus, le keystore et le truststore sont spécifiés à l'aide de références sous la forme :

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

Apigee vous recommande vivement de toujours utiliser des références au keystore et au truststore. Une référence est une variable contenant le nom du keystore ou du truststore, qui évite 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 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 le point de terminaison cible/serveur cible lui-même :

Pour modifier la valeur de la référence, vous n'avez pas besoin de contacter Google Cloud Customer Care.

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 truststore, vous devez contacter Google Cloud Customer Care.

Une troisième option consiste à utiliser des variables de flux :

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

Vous pouvez utiliser des variables de flux pour spécifier de manière dynamique un keystore ou un truststore, avec un effet semblable à l'utilisation d'une référence. Pour en savoir plus, consultez Utiliser des variables de flux pour définir les valeurs TLS/SSL de manière dynamique.

À propos de la configuration de TLS

Tous les clients Apigee, qu'ils utilisent un compte payant ou d'évaluation, ont un contrôle total sur la configuration des points de terminaison cibles/serveurs cibles. De plus, les clients Apigee disposant d'un compte payant ont un contrôle total sur 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 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 Apigee, 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és 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 pour le protocole TLS bidirectionnel (également appelé TLS mutuel ou mTLS).

Lorsqu'un certificat dans 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 le serveur cible/point de terminaison cible afin d'utiliser le nouveau keystore.

Lorsqu'un certificat dans un truststore expire et que vous utilisez une référence au truststore :

  1. vous créez un nouveau truststore ;
  2. vous 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, soit 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. vous mettez à jour la référence 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 le point de terminaison cible/serveur cible détermine la manière dont vous effectuez la mise à jour du certificat. Voici vos options :

  • 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 :

Type de configuration Comment mettre à jour/remplacer le certificat Utilisation
Référence (recommandé) Pour un keystore, créez un nouveau keystore avec un nouveau nom et un alias avec 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.

Inutile de contacter l'Assistance Apigee.
Variable de flux Pour un keystore, créez un nouveau keystore avec un nouveau nom et un alias avec le même nom ou 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, alias ou truststore.

Inutile de contacter l'Assistance Apigee.
Direct Créez un keystore, un alias et un truststore. Redéployez le proxy.
Direct Supprimez le keystore ou le truststore, et recréez-le avec le même nom. 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 (également appelé TLS mutuel ou mTLS) entre Apigee et le service de backend, contactez Google Cloud Customer Care pour redémarrer les processeurs de messages.
Direct Pour le truststore uniquement, importez un nouveau certificat dans le truststore. Contactez Google Cloud Customer Care pour redémarrer les processeurs de messages.