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.

Versions TLS non compatibles : Apigee n'est pas compatible avec TLS 1.0 ni TLS 1.1. Si vous utilisez ces protocoles dans la configuration de votre point de terminaison cible, le point de terminaison cible Apigee génère l'erreur messaging.adaptors.http.flow.SslHandshakeFailed.

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

Avertissement : 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. Si vous importez un nouveau certificat qui n'utilise pas de référence, mais qui spécifie directement le nom du keystore, les processeurs de messages d'exécution ne détecteront pas automatiquement la modification. Pour résoudre ce problème, vous devez contacter l'assistance Google Cloud afin de redémarrer vos processeurs de messages, ce qui peut entraîner une dégradation temporaire du service.

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. Toutefois, si vous utilisez des références, vous pouvez modifier la valeur des références pour refléter les nouveaux noms de keystore ou de truststore au lieu de modifier le point de terminaison cible/serveur cible. 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.

Remarque : Vous ne pouvez pas mettre à jour un keystore ou un truststore existant pour ajouter un nouveau certificat. Vous devez créer un nouveau keystore/truststore lors de la mise à jour d'un certificat. En règle générale, vous devez créer le nouveau keystore/truststore et importer le nouveau certificat avant l'expiration du certificat de l'ancien keystore/truststore. Cela vous permet de tester le nouveau keystore/truststore et de revenir à l'ancien keystore/truststore en cas de problème.

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

La méthode que vous utilisez pour spécifier le keystore et le truststore dans le point de terminaison cible ou le serveur cible détermine la manière dont vous effectuez la mise à jour du certificat. Vous pouvez utiliser des références, des noms directs ou des 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 / Impact
Référence (recommandé)	Keystore : créez un keystore avec un nouveau nom et un alias avec le même nom que l'ancien alias. Truststore : créez un truststore avec un nouveau nom. Le nom d'alias n'a pas d'importance. 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.	Mettez à jour la référence pour qu'elle pointe vers la nouvelle boutique. Inutile de contacter l'Assistance Apigee. Aucun temps d'arrêt.
Variable de flux	Keystore : créez un keystore avec un nouveau nom et un alias avec le même nom ou un nouveau nom. Truststore : créez un truststore avec un nouveau nom.	Transmettez la variable de flux mise à jour à chaque requête avec le nom du nouveau magasin. Inutile de contacter l'Assistance Apigee. Aucun temps d'arrêt.
Direct	Méthode 1 : Créer une boutique (recommandée pour éviter les temps d'arrêt) Créez un keystore ou un truststore avec un nouveau nom, puis importez le nouveau certificat (et la clé privée si vous créez un keystore).	Mettez à jour la configuration de votre point de terminaison cible ou de votre serveur cible pour spécifier directement le nouveau nom du magasin, puis redéployez le proxy d'API. Inutile de contacter l'Assistance Apigee.
Direct	Méthode 2a : Mise à jour sur place (supprimer et recréer) Supprimez le keystore ou le truststore, et recréez-le avec le même nom.	Les requêtes API échoueront pendant la période de suppression et de recréation. Étant donné que les processeurs de messages mettent en cache les magasins spécifiés directement, ils ne détecteront pas automatiquement le certificat mis à jour. Vous devez contacter Google Cloud Customer Care pour redémarrer les processeurs de messages.
Direct	Méthode 2b : Mise à jour sur place (importation du Truststore) Pour les truststores uniquement, importez un nouveau certificat directement dans le truststore existant.	Étant donné que les processeurs de messages mettent en cache les magasins spécifiés directement, ils ne détecteront pas automatiquement le nouveau certificat. Vous devez contacter Google Cloud Customer Care pour redémarrer les processeurs de messages.