Zugriff auf TLS-Verbindungsinformationen in einem API-Proxy

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Mit Edge können Sie virtuelle Hosts erstellen, die Ein-Wege- und Zwei-Wege-TLS unterstützen. Bei einer Möglichkeit für TLS gibt der Client eine Sitzungsanfrage an einen virtuellen Host aus, der auf einem Edge Router bereitgestellt ist. Der Router antwortet dann mit einem Zertifikat, das den öffentlichen Schlüssel des virtuellen Hosts enthält. Für ein signiertes Zertifikat kann der Client dann eine Anfrage zur Authentifizierung des Zertifikats an die Zertifizierungsstelle stellen.

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

  • Der Edge Router präsentiert dem TLS-Client sein Zertifikat, um sich zu authentifizieren. Der Client überprüft dann die Identität des Servers, bevor er sein Zertifikat an den Server sendet.
  • Der TLS-Client legt sein Zertifikat Edge zur Authentifizierung vor.

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. Ihr API-Proxy kann dann über Flussvariablen auf diese Informationen zugreifen, um zusätzliche Analysen und Validierungen durchzuführen.

Die Art der von Edge erfassten TLS-Informationen hängt davon ab, ob der virtuelle Host One-Wege- oder Zwei-Wege-TLS unterstützt. Bei One-Way-TLS kann Edge beispielsweise Informationen zur TLS-Chiffre oder zum TLS-Protokoll erfassen, die in der TLS-Verbindung verwendet werden.

Bei Zwei-Wege-TLS kann Edge dieselben Informationen wie für One-Way-TLS sowie auch Informationen zum Clientzertifikat erfassen. Edge kann beispielsweise den SHA1-Fingerabdruck des Clientzertifikats und das Clientzertifikat im PEM-Format erfassen.

Informationen für uni- und bidirektionale TLS erfassen

In der folgenden Tabelle sind die Flussvariablen aufgeführt, die TLS-Verbindungsinformationen enthalten, die von Edge erfasst wurden und für den Zugriff im API-Proxy verfügbar sind. Diese Informationen werden sowohl für uni- als auch für bidirektionale TLS erfasst. Dazu setzen Sie <ConnectionProperties> in der Definition des virtuellen Hosts auf „true“:

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 Flussvariable ist verfügbar, wenn Sie <ConnectionProperties> oder <ClientProperties> oder auf „true“ festlegen.

Zusätzliche TLS-Informationen bei bidirektionaler TLS

In der folgenden Tabelle sind die Flussvariablen aufgeführt, die Details zum Clientzertifikat enthalten, die von Edge in Zwei-Wege-TLS erfasst wurden. Diese Informationen werden für Zwei-Wege-TLS erfasst, indem <ClientProperties> in der Definition des virtuellen Hosts auf „true“ gesetzt wird:

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 Flussvariable ist verfügbar, wenn Sie <ConnectionProperties> oder <ClientProperties> auf „true“ setzen.

Virtuellen Host zum Erfassen von TLS-Informationen konfigurieren

Wenn Sie den virtuellen Host für die Erfassung von TLS-Informationen konfigurieren möchten, legen Sie die folgenden Attribute unter <PropagateTLSInformation> auf true fest.

  • <ConnectionProperties>: Aktivieren Sie die Erfassung von TLS-Verbindungsinformationen sowohl für One-Way-TLS als auch für Zwei-Wege-TLS. Der Standardwert ist false.
  • <ClientProperties>: Ermöglicht die Erfassung zusätzlicher Informationen für Zwei-Wege-TLS. Der Standardwert ist false.

Die folgende Definition eines virtuellen Hosts verwendet beispielsweise Zwei-Wege-TLS und ermöglicht die Erfassung beider Arten von TLS-Informationen:

<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 Attribute so fest:

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

Größenbeschränkungen für Header festlegen

Wenn Sie die Erfassung von TLS-Informationen auf einem virtuellen Host aktivieren, leitet Edge diese Informationen mithilfe von HTTP-Headern weiter. Daher müssen Sie darauf achten, dass die Header-Größenbeschränkungen entsprechend festgelegt sind, je nachdem, ob Sie Edge für die Cloud oder Edge für die Private Cloud verwenden:

  • Edge für die Cloud: Apigee legt die Headergrößen entsprechend fest.
  • Edge für die 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 die Richtlinie AssignMessage verwenden, um auf sie zuzugreifen, und in JavaScript mit der JavaScript-Richtlinie darauf zugreifen.

Sie können auch auf die Flussvariablen in einem <Condition>-Element eines Proxy- oder Zielablaufs oder in einem <Step> oder <RouteRule> verweisen. Sie können beispielsweise eine Anfrage basierend auf der SN des Clients an verschiedene Ziele weiterleiten.

Weitere Informationen: