Zugriff auf TLS-Verbindungsinformationen in einem API-Proxy

Sie lesen gerade die Apigee Edge -Dokumentation.
Zur Apigee X -Dokumentation. info

Mit Edge können Sie virtuelle Hosts erstellen, die unilaterale und bilaterale TLS unterstützen. Bei unilateraler TLS, sendet der Client eine Sitzungsanfrage an einen virtuellen Host, der auf einem Edge-Router bereitgestellt wird. Der Router antwortet mit einem Zertifikat, das den öffentlichen Schlüssel des virtuellen Hosts enthält. Bei einem signierten Zertifikat kann der Client dann eine Anfrage an die Zertifizierungsstelle (Certificate Authority, CA) senden, um das Zertifikat zu authentifizieren.

Bei bilateraler TLS übergeben sowohl der Client als auch Edge Zertifikate, die im Rahmen einer Anfrage validiert werden:

  • Der Edge-Router stellt dem TLS-Client sein Zertifikat zur Authentifizierung bereit. Der Client überprüft dann die Identität des Servers, bevor er sein Zertifikat an den Server sendet.
  • Der TLS-Client stellt Edge sein Zertifikat zur Authentifizierung bereit.

Weitere Informationen finden Sie unter Informationen zu virtuellen Hosts.

TLS-Verbindungsinformationen erfassen

Während einer Anfrage an einen API-Proxy über einen virtuellen Host, der TLS unterstützt, kann Edge Informationen über die TLS-Verbindung erfassen. Der API-Proxy kann dann über Ablaufvariablen auf diese Informationen zugreifen, um zusätzliche Analysen und Validierungen durchzuführen.

Der von Edge erfasste Typ der TLS-Informationen hängt davon ab, ob der virtuelle Host unilaterale oder bilaterale TLS unterstützt. Bei unilateraler TLS kann Edge beispielsweise Informationen zur TLS-Chiffre oder zum TLS-Protokoll erfassen, das in der TLS-Verbindung verwendet wird.

Bei bilateraler TLS kann Edge dieselben Informationen erfassen, die für unilaterale TLS aufgezeichnet werden, sowie Informationen über das Zertifikat des Clients. Edge kann beispielsweise den SHA1-Fingerabdruck des Clientzertifikats und des Clientzertifikats im PEM-Format erfassen.

Informationen zu uni- und bidirektionaler TLS

In der folgenden Tabelle sind die Ablaufvariablen mit TLS-Verbindungsinformationen aufgeführt, die von Edge erfasst werden und die für den Zugriff auf den API-Proxy verfügbar sind. Diese Informationen werden sowohl für unilaterale als auch für bilaterale TLS erfasst, indem Sie <ConnectionProperties> auf „true“ setzen in der Definition des virtuellen Hosts:

Ablaufvariable Beschreibung
tls.cipher Die Chiffren, die von der TLS-Verbindung verwendet werden.
tls.protocol Das Protokoll, das von der TLS-Verbindung verwendet wird.
tls.server.name Der angeforderte SNI-Servername.
tls.session.id

Die Sitzungs-ID.

Diese Ablaufvariable ist verfügbar, wenn Sie entweder <ConnectionProperties> oder <ClientProperties> auf „true“ setzen.

Zusätzliche TLS-Informationen bei bidirektionaler TLS

In der folgenden Tabelle sind die Ablaufvariablen mit Details zum Clientzertifikat aufgeführt, die von Edge in bilateraler TLS erfasst wurden. Diese Informationen werden für bilaterale TLS erfasst, indem Sie in der Definition des virtuellen Hosts <ClientProperties> auf „true“ setzen:

Ablaufvariable Beschreibung
tls.client.s.dn Der Betreff "Distinguished Name (DN)" des Clientzertifikats.
tls.client.i.dn Der Aussteller-DN (Distinguished Name, DN) des Clientzertifikats.
tls.client.raw.cert Das Clientzertifikat im PEM-Format.
tls.client.cert.serial Die Seriennummer des Clientzertifikats.
tls.client.cert.fingerprint SHA1-Fingerabdruck des Clientzertifikats.
tls.session.id

Die Sitzungs-ID.

Diese Ablaufvariable ist verfügbar, wenn Sie entweder <ConnectionProperties> oder <ClientProperties> auf „true“ setzen.

Virtuellen Host für die Erfassung von TLS-Informationen konfigurieren

Wenn Sie den virtuellen Host so konfigurieren möchten, dass TLS-Informationen erfasst werden, setzen Sie die folgenden Eigenschaften unter <PropagateTLSInformation> auf true.

  • <ConnectionProperties>: Aktivieren Sie die Erfassung von TLS-Verbindungsinformationen für unilaterale und bilaterale TLS. Der Standardwert ist false.
  • <ClientProperties>: Aktivieren Sie die Erfassung zusätzlicher Informationen für bilaterale TLS. Der Standardwert ist false.

In der folgenden Definition des virtuellen Hosts wird beispielsweise bilaterale TLS verwendet und die Erfassung beider Arten von TLS-Informationen aktiviert:

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

Wenn Sie einen JSON-Text übergeben, legen Sie die Eigenschaften so fest:

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

Grenzwerte für die Kopfzeilengröße festlegen

Wenn Sie die Erfassung von TLS-Informationen auf einem virtuellen Host aktivieren, übergibt Edge diese Informationen über HTTP-Header. Sie müssen daher die Grenzwerte für die Kopfzeilengröße entsprechend festlegen, je nachdem, ob Sie Edge for the Cloud oder Edge for the Private Cloud verwenden:

  • Edge for the Cloud: Apigee legt die Kopfzeilengrößen entsprechend fest.
  • Edge for the Private Cloud: Feature nicht verfügbar.

Auf Ablaufvariablen in einem API-Proxy zugreifen

Über Ihren API-Proxy können Sie auf die TLS-Ablaufvariablen zugreifen und sie prüfen. Sie können beispielsweise mit der Richtlinie AssignMessage darauf zugreifen oder mit der JavaScript-Richtlinie in JavaScript darauf zugreifen.

Sie können auch auf die Ablaufvariablen in einem <Condition> Element eines Proxys oder Zielablaufs, oder in einem <Step> oder <RouteRule> verweisen. Sie können beispielsweise eine Anfrage je nach SN des Clients an verschiedene Ziele weiterleiten.

Weitere Informationen: