Optionen für die TLS-Konfiguration

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

Dieses Dokument enthält eine Übersicht über die Konfiguration von TLS auf Edge für zwei Funktionsbereiche:

  1. Zugriff auf Ihre API-Proxys von API-Clients. Verwenden Sie virtuelle Hosts auf dem Edge Router, um TLS zu konfigurieren.
  2. Zugriff auf Ihre Backend-Dienste durch Edge. Verwenden Sie Zielendpunkte und Zielserver auf dem Edge Message Processor, um TLS zu konfigurieren.

Beide Zugriffstypen werden unten dargestellt:

TLS-Optionen auf einem virtuellen Host oder Zielendpunkt/Zielserver festlegen

Ein virtueller Host kann durch ein XML-Objekt in folgendem Format dargestellt werden:

<VirtualHost name="secure">
    ...
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTruststoreRef</TrustStore> 
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

Der Bereich des virtuellen Hosts, den Sie zum Konfigurieren von TLS ändern, wird durch das Tag <SSLInfo> definiert. Sie verwenden dasselbe <SSLInfo>-Tag, um einen Zielendpunkt oder Zielserver zu konfigurieren.

In folgender Tabelle werden die TLS-Konfigurationselemente beschrieben, die vom <SSLInfo>-Tag verwendet werden:

Element Beschreibung
<Enabled>

Aktiviert One-Way-TLS zwischen Edge und dem API-Client oder zwischen Edge und dem Ziel-Back-End.

Für einen virtuellen Host müssen Sie einen Schlüsselspeicher definieren, der Zertifikat und privaten Schlüssel enthält.

<ClientAuthEnabled>

Aktiviert die Zwei-Wege-TLS-Verbindung zwischen Edge und dem API-Client oder zwischen Edge und dem Ziel-Back-End.

Zum Aktivieren der Zwei-Wege-TLS-Funktion müssen Sie in der Regel einen Truststore in Edge einrichten.

<KeyStore> Der Schlüsselspeicher.
<KeyAlias> Der Alias, der beim Hochladen eines Zertifikats und eines privaten Schlüssels in den Schlüsselspeicher angegeben wurde.
<TrustStore> Der Truststore.
<IgnoreValidationErrors>

Falls wahr, ignoriert Edge TLS-Zertifikatsfehler. Gültig beim Konfigurieren der TLS für Zielserver und Zielendpunkte und beim Konfigurieren von virtuellen Hosts, die bidirektionale TLS verwenden. Der Standardwert ist "false".

Wenn das Back-End-System SNI verwendet und ein Zertifikat mit einem Subject Distinguished Name (DN) zurückgibt, der nicht mit dem Hostnamen übereinstimmt, gibt es bei der Verwendung mit einem Zielendpunkt/Zielserver keine Möglichkeit, den Fehler zu ignorieren und die Verbindung schlägt fehl.

<CommonName>

Falls angegeben, ein Wert, anhand dessen der Common Name des Zielzertifikats validiert wird. Dieser Wert gilt nur für TargetEndpoint- und TargetServer-Konfigurationen. Er gilt nicht für VirtualHost-Konfigurationen.

Standardmäßig wird der angegebene Wert exakt mit dem allgemeinen Namen des Zielzertifikats abgeglichen. Wenn Sie beispielsweise *.myhost.com als Wert für <CommonName> verwenden, wird der Ziel-Hostname nur dann abgeglichen und validiert, wenn der genaue Wert *.myhost.com als allgemeinen Namen im Zielzertifikat angegeben ist.

Optional kann Apigee den Abgleich mit Platzhaltern mithilfe des Attributs wildcardMatch durchführen.

Beispielsweise wird ein allgemeiner Name, der in einem Zielzertifikat als abc.myhost.com angegeben ist, abgeglichen und validiert, wenn das Element <CommonName> so angegeben wird:

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

Informationen zum Festlegen der Elemente <KeyStore> und <TrustStore>

Im Beispiel für einen virtuellen Host oben werden Keystore und Truststore durch references im folgenden Format angegeben:

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

Apigee empfiehlt dringend, dass Sie Verweise auf Schlüsselspeicher und Truststore verwenden. Ein Verweis ist eine Variable, die den Namen des Schlüsselspeichers oder Truststore enthält, statt den Namen des Schlüsselspeichers direkt anzugeben. In diesem Beispiel:

  • myKeystoreRef ist eine Referenz, die den Namen des Schlüsselspeichers enthält. In diesem Beispiel lautet der Name des Schlüsselspeichers myKeystore.
  • myTruststoreRef ist eine Referenz, die den Namen des Truststore enthält. In diesem Beispiel lautet der Name des Truststore myTruststore.

Läuft ein Zertifikat ab, müssen Sie den virtuellen Host oder Zielendpunkt/Zielserver aktualisieren, um den Keystore oder Truststore mit dem neuen Zertifikat anzugeben. Der Vorteil eines Verweises besteht darin, dass Sie den Wert des Verweises ändern können, um den Schlüsselspeicher oder Truststore zu ändern, ohne den virtuellen Host oder Zielendpunkt/Zielserver selbst ändern zu müssen:

  • Für Cloud-Kunden: Wenn Sie den Wert der Referenz ändern, müssen Sie sich nicht an den Apigee Edge-Support wenden.
  • Für Private Cloud-Kunden: Wenn Sie den Wert der Referenz ändern, müssen Sie Edge-Komponenten wie Router und Nachrichtenprozessor nicht neu starten.

Alternativ können Sie den Schlüsselspeicher- und den Truststore-Namen direkt angeben:

<KeyStore>myKeystore</KeyStore>
<TrustStore>myTruststore</TrustStore> 

Wenn Sie den Namen des Schlüsselspeichers oder Truststores direkt angeben, müssen Cloud-Kunden den Apigee Edge-Support kontaktieren und Private Cloud-Kunden müssen bestimmte Edge-Komponenten neu starten, um das Zertifikat zu aktualisieren.

Eine dritte Option ist nur für Zielendpunkte/Zielserver die Verwendung von Flussvariablen:

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

Ablaufvariablen funktionieren für Zielendpunkte/Zielserver, mit denen Sie den Schlüsselspeicher oder Truststore wie Verweise aktualisieren können. Sie funktionieren jedoch nicht mit virtuellen Hosts. Sie müssen bei jeder Anfrage Informationen zum Schlüsselspeicher, Alias und Truststore senden.

Einschränkungen bei der Verwendung von Verweisen auf Schlüsselspeicher und Truststore

Kostenpflichtige Cloud-Kunden und alle Private Cloud-Kunden, die TLS konfigurieren, müssen die folgende Einschränkung berücksichtigen, wenn sie Verweise auf Schlüsselspeicher und Truststores verwenden:

  • Sie können Schlüsselspeicher- und Truststore-Verweise nur auf virtuellen Hosts verwenden, wenn Sie die TLS für die Apigee-Router beenden.
  • Wenn sich vor den Apigee-Routern ein Load-Balancer befindet und Sie TLS auf dem Load-Balancer beenden, können Sie in virtuellen Hosts keine Keystore- und Truststore-Verweise verwenden.

Wenn Ihr vorhandener virtueller Host einen literalen Schlüsselspeicher- oder Truststore-Namen verwendet

Vorhandene virtuelle Hosts in Edge sind möglicherweise nicht für die Verwendung von Verweisen auf Schlüsselspeicher und Truststores konfiguriert. In diesem Fall können Sie den virtuellen Host so aktualisieren, dass er Verweise verwendet.

  1. Edge für die Cloud

    Wenn Sie den virtuellen Host so ändern möchten, dass ein Verweis auf den Schlüsselspeicher verwendet wird, müssen Sie den Apigee Edge-Support verwenden.

  2. Edge für die Private Cloud

    So konvertieren Sie den virtuellen Host zur Verwendung einer Referenz:

    1. Aktualisieren Sie den virtuellen Host, um eine Referenz zu verwenden.
    2. Starten Sie die Router neu.
    Weitere Informationen finden Sie unter „Virtuellen Host zur Verwendung von Verweisen auf den Schlüsselspeicher und Truststore ändern“ unter TLS-Zugriff auf eine API für die Private Cloud konfigurieren.

Zertifikat und Schlüssel für kostenlose Apigee-Testversion verwenden

Wenn Sie ein kostenpflichtiges Edge for Cloud-Konto und noch kein TLS-Zertifikat und keinen TLS-Schlüssel haben, können Sie einen virtuellen Host erstellen, der das Zertifikat und den Schlüssel der kostenlosen Apigee-Testversion verwendet. Das bedeutet, dass Sie den virtuellen Host erstellen können, ohne zuvor einen Schlüsselspeicher zu erstellen.

Ein XML-Objekt, das den virtuellen Host mithilfe des kostenlosen Apigee-Testzertifikats und -schlüssels definiert, lässt die Elemente <KeyStore> und <KeyAlias> weg und ersetzt sie wie unten gezeigt durch das Element <UseBuiltInFreeTrialCert>:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

Wenn Sie die bidirektionale TLS nutzen, müssen Sie das Element <ClientAuthEnabled> dennoch auf true festlegen und einen Truststore angeben. Nutzen Sie dazu einen Verweis mit dem Element <TrustStore>.

Weitere Informationen finden Sie unter Virtuelle Hosts für die Cloud konfigurieren.

Informationen zur TLS-Konfiguration

Zwei Hauptfaktoren bestimmen, wie Sie die TLS-Konfiguration durchführen:

  • Sind Sie Kunde von Edge Cloud oder Private Cloud?
  • Wie werden abgelaufene oder ablaufende Zertifikate aktualisiert?

Optionen bei der Konfiguration von Clouds und Privaten Clouds

Die folgende Tabelle zeigt die verschiedenen Konfigurationsoptionen für Cloud- und Private Cloud-Kunden:

Private Cloud Cloud
Virtueller Host Volle Kontrolle Die vollständige Kontrolle ist nur für kostenpflichtige Konten verfügbar
Zielendpunkt/Zielserver Volle Kontrolle Volle Kontrolle

Private Cloud-Kunden haben die vollständige Kontrolle über die Konfiguration von virtuellen Hosts und Zielendpunkten/Zielservern. Dazu gehört die Möglichkeit, virtuelle Hosts zu erstellen und zu löschen und alle Attribute auf einem virtuellen Host festzulegen.

Alle Cloud-Kunden, sowohl zahlende als auch Evaluierungskunden, haben die vollständige Kontrolle über die Konfiguration von Zielendpunkten/Zielservern. Darüber hinaus haben zahlende Cloud-Kunden die vollständige Kontrolle über virtuelle Hosts, einschließlich TLS-Attributen.

Umgang mit abgelaufenen Zertifikaten

Wenn ein TLS-Zertifikat abläuft oder Ihre Systemkonfiguration so geändert wird, dass das Zertifikat nicht mehr gültig ist, muss das Zertifikat aktualisiert werden. Wenn Sie die TLS für einen virtuellen Host oder Zielendpunkt/Zielserver konfigurieren, sollten Sie vor der Konfiguration festlegen, wie Sie dieses Update durchführen.

Vorgehensweise bei abgelaufenem Zertifikat

In Edge werden Zertifikate an einem von zwei Orten gespeichert:

  • Schlüsselspeicher: Enthält das TLS-Zertifikat und den privaten Schlüssel, um die Entität während des TLS-Handshakes zu identifizieren.
  • Truststore: Enthält vertrauenswürdige Zertifikate auf einem TLS-Client, mit denen das dem Client dargestellte Zertifikat eines TLS-Servers validiert wird. Diese Zertifikate sind normalerweise selbstsignierte Zertifikate, von einer vertrauenswürdigen Zertifizierungsstelle signierte Zertifikate oder Zertifikate, die im Rahmen von bidirektionaler TLS-Authentifizierung verwendet werden.

Wenn ein Zertifikat in einem Schlüsselspeicher abläuft und Sie einen Verweis auf den Schlüsselspeicher verwenden, können Sie kein neues Zertifikat in den Schlüsselspeicher hochladen. Gehen Sie stattdessen so vor:

  1. Erstellen Sie einen neuen Schlüsselspeicher.
  2. Laden Sie ein neues Zertifikat mit demselben Aliasnamen wie dem des alten Schlüsselspeichers in den neuen Schlüsselspeicher hoch.
  3. Aktualisieren Sie den Verweis in Ihrem virtuellen Host oder Zielserver/Zielendpunkt, um den neuen Truststore zu verwenden.

Wenn ein Zertifikat in einem Truststore abläuft und Sie einen Verweis auf den Truststore verwenden:

  1. Erstellen Sie einen neuen Truststore.
  2. Laden Sie das neue Zertifikat in den neuen Truststore hoch. Der Aliasname spielt für Truststores keine Rolle. Hinweis: Wenn ein Zertifikat Teil einer Kette ist, müssen Sie entweder eine einzelne Datei mit allen Zertifikaten erstellen und diese Datei in einen einzelnen Alias hochladen oder alle Zertifikate in der Kette separat mit dem Truststore verknüpft werden.
  3. Aktualisieren Sie den Verweis in Ihrem virtuellen Host oder Zielserver/Zielendpunkt, um den neuen Truststore zu verwenden.

Zusammenfassung der Methoden zum Aktualisieren eines abgelaufenen Zertifikats

Die Methode, die Sie zur Angabe des Namens des Schlüsselspeichers oder des Truststores auf dem virtuellen Host oder Zielendpunkt/Zielserver nutzen, richtet sich nach der verwendeten Methode. Sie können Folgendes angeben:

  • Verweise
  • Direkte Namen
  • Ablaufvariablen

Jede dieser Methoden hat unterschiedliche Auswirkungen auf den Aktualisierungsprozess, wie in der folgenden Tabelle beschrieben. Wie Sie sehen, bieten Referenzen sowohl für Cloud- als auch für Private Cloud-Kunden die größte Flexibilität:

Konfigurationstyp Zertifikat aktualisieren/ersetzen Private Cloud Cloud
Referenz (empfohlen) Erstellen Sie für einen Schlüsselspeicher einen neuen Schlüsselspeicher mit einem neuen Namen und einem Alias mit demselben Namen wie dem alten Alias.

Erstellen Sie bei einem Truststore einen Truststore mit einem neuen Namen.

Aktualisieren Sie den Verweis auf den Schlüsselspeicher oder Truststore.

Es ist kein Neustart des Routers oder Nachrichtenprozessors erforderlich.

Aktualisieren Sie den Verweis auf den Schlüsselspeicher oder Truststore.

Sie müssen den Apigee-Support nicht kontaktieren.

Ablaufvariablen (nur Zielendpunkt) Erstellen Sie für einen Schlüsselspeicher einen neuen Schlüsselspeicher mit einem neuen Namen und einem Alias mit demselben oder einem neuen Namen.

Erstellen Sie bei einem Truststore einen Truststore mit einem neuen Namen.

Übergeben Sie die aktualisierte Ablaufvariable bei jeder Anfrage mit dem Namen des neuen Schlüsselspeichers, Alias oder Truststores.

Es ist kein Neustart des Routers oder Nachrichtenprozessors erforderlich.

Übergeben Sie die aktualisierte Ablaufvariable bei jeder Anfrage mit dem Namen des neuen Schlüsselspeichers, Alias oder Truststores.

Sie müssen den Apigee-Support nicht kontaktieren.

Direkt Erstellen Sie einen neuen Schlüsselspeicher, einen Alias oder einen Truststore. Aktualisieren Sie den virtuellen Host und starten Sie die Router neu.

Wenn der Truststore von einem Zielendpunkt/Zielserver verwendet wird, stellen Sie den Proxy neu bereit.

Wenden Sie sich bei virtuellen Hosts an den Apigee Edge-Support, um die Router neu zu starten.

Wenn der Truststore von einem Zielendpunkt/Zielserver verwendet wird, stellen Sie den Proxy neu bereit.

Direkt Löschen Sie den Schlüsselspeicher oder Truststore und erstellen Sie ihn noch einmal mit demselben Namen. Es ist kein Update des virtuellen Hosts erforderlich, kein Routerneustart erforderlich. API-Anfragen schlagen jedoch fehl, bis der neue Schlüsselspeicher und der Alias festgelegt wurden.

Wenn der Schlüsselspeicher für die Zwei-Wege-TLS-Verbindung zwischen Edge und dem Back-End-Dienst verwendet wird, starten Sie die Nachrichtenprozessoren neu.

Der virtuelle Host muss nicht aktualisiert werden. Allerdings schlagen API-Anfragen fehl, bis der neue Schlüsselspeicher und der neue Alias festgelegt sind.

Wenn der Schlüsselspeicher für die Zwei-Wege-TLS-Verbindung zwischen Edge und dem Back-End-Dienst verwendet wird, wenden Sie sich an den Apigee Edge-Support, um die Nachrichtenprozessoren neu zu starten.

Direkt Laden Sie nur für Truststores ein neues Zertifikat in den Truststore hoch. Wenn der Truststore von einem virtuellen Host verwendet wird, starten Sie die Router neu.

Wenn der Truststore von einem Zielendpunkt/Zielserver verwendet wird, starten Sie die Message Processor neu.

Wenden Sie sich bei virtuellen Hosts an den Apigee Edge-Support, um die Edge Router neu zu starten.

Wenn der Truststore von einem Zielendpunkt/Zielserver verwendet wird, wenden Sie sich an den Apigee Edge-Support, um die Message Processors neu zu starten.