Options de configuration de TLS

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

Consultez la documentation d'Apigee Edge.

Cette section explique 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>
    </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 la section 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>`	Active le protocole TLS unidirectionnel entre Apigee et le client API, ou entre Apigee et le backend cible.
`<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 incompatible 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 positive (`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.
`<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. La valeur par défaut est false. 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.

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

Modifier la valeur de la référence ne vous oblige pas à contacter l'assistance Apigee.

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 l'assistance Apigee.

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

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

Les variables de flux vous permettent de mettre à jour le keystore ou le truststore comme les références. Pour en savoir plus, consultez la section 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'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. 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é 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 (également appelé TLS mutuel ou mTLS).

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 :

Créez un nouveau keystore.
Importez le nouveau certificat dans le nouveau keystore en utilisant le même nom d'alias que dans l'ancien keystore.
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 arrive à expiration et que vous utilisez une référence au truststore, vous :

Créez un nouveau truststore.
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.
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. Vous pouvez indiquer :

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 dans le keystore ou le 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 nouveau 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 l'Assistance Apigee pour redémarrer les processeurs de messages.
Directe	Pour le truststore uniquement, importez un nouveau certificat dans le truststore.	Contactez l'assistance Apigee pour redémarrer les processeurs de messages.