Accéder aux informations de connexion TLS dans un proxy d'API

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Edge vous permet de créer des hôtes virtuels prenant en charge TLS unidirectionnelle et bidirectionnelle. Avec TLS à sens unique, le client envoie une requête de session à un hôte virtuel déployé sur un routeur Edge et le routeur répond par un certificat contenant la clé publique de l'hôte virtuel. Pour un certificat signé, le client peut ensuite demander à l'autorité de certification (CA) d'authentifier le certificat.

Dans le protocole TLS bidirectionnel, les certificats client et Edge sont tous deux validés dans le cadre d’une requête:

  • Le routeur Edge présente son certificat au client TLS pour s'authentifier. Le client vérifie ensuite l’identité du serveur avant d’envoyer son certificat au serveur.
  • Le client TLS présente son certificat à Edge pour s'authentifier.

Pour en savoir plus, consultez la section À propos des hôtes virtuels.

Récupérer des informations de connexion TLS

Lors d'une requête adressée à un proxy d'API via un hôte virtuel prenant en charge TLS, Edge peut capturer sur la connexion TLS. Votre proxy d'API peut ensuite accéder à ces informations via des variables de flux pour effectuer une analyse et une validation supplémentaires.

Le type d'informations TLS capturées par Edge varie selon que l'hôte virtuel prend en charge ou non TLS unidirectionnel ou bidirectionnel. Par exemple, pour TLS à sens unique, Edge peut capturer des informations sur le Chiffrement TLS ou protocole TLS utilisé dans la connexion TLS.

Pour un TLS bidirectionnel, Edge peut capturer toutes les mêmes informations que celles capturées pour le TLS à sens unique, et capturer également des informations sur le certificat du client. Par exemple, Edge peut capturer l'empreinte SHA1 du certificat client et du certificat client au format PEM.

Capturer des informations pour TLS unidirectionnelle et bidirectionnelle

Le tableau suivant répertorie les variables de flux qui contiennent des informations de connexion TLS capturées par Edge et disponibles pour l'accès dans le proxy d'API. Ces informations sont collectées pour les entrées à sens unique et le protocole TLS bidirectionnel en définissant <ConnectionProperties> sur "true" Définition de l'hôte virtuel:

Variable de flux Description
tls.cipher Algorithme de chiffrement utilisé par la connexion TLS.
tls.protocol Protocole utilisé par la connexion TLS.
tls.server.name Nom du serveur SNI demandé.
tls.session.id

Identifiant de session.

Cette variable de flux est disponible lorsque vous définissez <ConnectionProperties> ou <ClientProperties> ou "true".

Récupérer des informations TLS supplémentaires lors du protocole TLS bidirectionnel

Le tableau suivant répertorie les variables de flux qui contiennent les détails du certificat client capturés par Edge avec un protocole TLS bidirectionnel. Ces informations sont capturées pour le protocole TLS bidirectionnel en définissant <ClientProperties> sur "true" dans la définition de l'hôte virtuel:

Variable de flux Description
tls.client.s.dn Nom distinctif de l'objet du certificat client
tls.client.i.dn Émetteur du nom distinctif du certificat client
tls.client.raw.cert Certificat client au format PEM
tls.client.cert.serial Numéro de série du certificat client
tls.client.cert.fingerprint Empreinte SHA1 du certificat client
tls.session.id

Identifiant de session.

Cette variable de flux est disponible lorsque vous définissez <ConnectionProperties> ou <ClientProperties> sur "true".

Configurer un hôte virtuel pour capturer les informations TLS

Pour configurer l'hôte virtuel afin qu'il capture les informations TLS, définissez les propriétés suivantes sous <PropagateTLSInformation> par true.

  • <ConnectionProperties>: active la capture des informations de connexion TLS. pour le protocole TLS unidirectionnel et bidirectionnel. La valeur par défaut est false.
  • <ClientProperties>: active la capture d'informations supplémentaires. pour le protocole TLS bidirectionnel. La valeur par défaut est false.

Par exemple, la définition d'hôte virtuel suivante utilise le protocole TLS bidirectionnel et active la capture les deux types d'informations TLS:

<VirtualHost name="secure">
    ....
    <SSLInfo>
        <Enabled>true</Enabled>
        # Enable two-way TLS.
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <KeyAlias>ks-alias</KeyAlias>
        <KeyStore>ref://ks-ref</KeyStore>
        <TrustStore>ref://ts-ref</TrustStore>
    </SSLInfo>
    <PropagateTLSInformation>
        <ConnectionProperties>true</ConnectionProperties>
        <ClientProperties>true</ClientProperties>
    </PropagateTLSInformation>
</VirtualHost>

Si vous transmettez un corps JSON, définissez les propriétés comme suit:

  "propagateTLSInformation" : {
    "connectionProperties" : true,
    "clientProperties" : true
  }

Définir des limites de taille d'en-tête

Lorsque vous activez la capture d'informations TLS sur un hôte virtuel, Edge transmet ces informations à l'aide d'en-têtes HTTP. Vous devez donc vous assurer que les limites de taille d'en-tête sont correctement définies. selon que vous utilisez Edge pour le cloud ou Edge pour le cloud privé:

  • Edge for the Cloud: Apigee définit les tailles d'en-tête de manière appropriée.
  • Edge pour le cloud privé: fonctionnalité non disponible.

Accéder aux variables de flux dans un proxy d'API

À partir de votre proxy d'API, vous pouvez accéder aux variables de flux TLS et les inspecter. Par exemple, vous pouvez utiliser la méthode AssignMessage pour y accéder, y accéder en JavaScript avec la règle JavaScript.

Vous pouvez également référencer les variables de flux dans un élément <Condition> d'un flux proxy ou cible, ou dans <Step> ou <RouteRule>. Par exemple, vous pouvez acheminer une demande à différentes cibles en fonction du numéro de série du client.

Pour en savoir plus, consultez les pages suivantes: