Optionen für die TLS-Konfiguration

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

In diesem Abschnitt wird gezeigt, wie Sie TLS für Traffic von einem Proxy zu einem Ziel konfigurieren.

Informationen zum Festlegen von TLS-Optionen in einem Zielendpunkt oder Zielserver

Ein Ziel kann durch ein XML-Objekt wie das folgende dargestellt werden:

<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>
        <Protocols>myProtocols</Protocols>
        <Ciphers>myCipher</Ciphers>
    </SSLInfo>
</HTTPTargetConnection>

Der Bereich der Zielendpunktkonfiguration, die Sie ändern, um TLS zu konfigurieren, wird durch das Tag <SSLInfo> definiert. Verwenden Sie dasselbe <SSLInfo>-Tag, um einen Zielendpunkt oder einen Zielserver zu konfigurieren.

Informationen zu den untergeordneten Elementen von <SSLInfo> finden Sie unter TLS/SSL-TargetEndpoint-Konfiguration.

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

Element Beschreibung
<Enabled> Der <SSLInfo>-Block kann sowohl für uni- als auch für bidirektionale TLS/SSL verwendet werden.

Wenn true festgelegt ist, gibt <Enabled> an, dass der Block <SSLInfo> verwendet werden soll. Wenn false festgelegt ist, wird der Block <SSLInfo> ignoriert.

Der Standardwert von <Enabled> ist true, wenn <URL> das HTTPS-Protokoll angibt, und falsewenn <URL> HTTP festlegt.
<Enforce>

Erzwingt strenges SSL zwischen Apigee und dem Ziel-Backend.

Wenn dieser Wert auf true gesetzt ist, schlagen Verbindungen bei Zielen mit ungültigen Zertifikaten, abgelaufenen Zertifikaten, selbst signierten Zertifikaten, Zertifikaten mit nicht übereinstimmenden Hostnamen sowie Zertifikaten mit einer nicht vertrauenswürdigen Stammzertifizierungsstelle fehl. Der Fehlercode 4xx oder 5xx wird zurückgegeben.

Wenn kein Wert festgelegt oder auf false festgelegt ist, hängt das Ergebnis von Verbindungen zu Ziel-Back-Ends mit problematischen Zertifikaten von der Einstellung von <IgnoreValidationErrors> ab (siehe unten). Eine Erfolgsantwort (2xx) kann unter bestimmten Bedingungen auftreten, wenn <IgnoreValidationErrors> auf true gesetzt ist.
<ClientAuthEnabled>

Aktiviert die Zwei-Wege-TLS (auch gegenseitige TLS oder mTLS genannt) zwischen Apigee und dem API-Client oder zwischen Apigee und dem Ziel-Backend.

Für die Aktivierung der bidirektionalen TLS müssen Sie normalerweise einen Truststore auf Apigee und einen Truststore einrichten.
<KeyStore> Einen Schlüsselspeicher, der private Schlüssel für die ausgehende Clientauthentifizierung verwendet
<KeyAlias> Der Alias, der beim Hochladen eines Zertifikats und eines privaten Schlüssels in den Schlüsselspeicher angegeben wurde.
<TrustStore> Einen Schlüsselspeicher mit vertrauenswürdigen Serverzertifikaten.
<IgnoreValidationErrors>

Gibt an, ob Validierungsfehler ignoriert werden. Wenn das Backend-System SNI nutzt und ein Zertifikat mit einem Subjekt-DN (Subject Distinguished Name) zurückgibt, der nicht mit dem Hostnamen übereinstimmt, kann der Fehler nicht ignoriert werden und die Verbindung schlägt fehl.

Hinweis: Wenn <Enforce> auf true gesetzt ist, wird der Wert von <IgnoreValidationErrors> ignoriert.
<Ciphers>

Unterstützte Chiffren für ausgehende TLS/SSL. Wenn keine Chiffren angegeben sind, sind alle für die JVM verfügbaren Chiffren erlaubt.

Fügen Sie die folgenden Elemente hinzu, um die Chiffren einzuschränken:

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
<Protocols>

Unterstützte Protokolle für ausgehendes TLS/SSL. Wenn keine Protokolle angegeben sind, sind alle für die JVM verfügbaren Protokolle zulässig.

Wenn Sie Protokolle einschränken möchten, geben Sie sie explizit an. So lassen Sie beispielsweise nur TLS v1.2 oder TLS v1.3 zu:

<Protocols>
 <Protocol>TLSv1.2</Protocol>
 <Protocol>TLSv1.3</Protocol>
</Protocols>

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

Im obigen Beispiel werden der Schlüsselspeicher und Truststore durch Verweise im folgenden Form 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 Zielendpunkt/Zielserver aktualisieren, um den Schlüsselspeicher 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 Zielendpunkt/Zielserver selbst ändern zu müssen:

Sie müssen sich nicht an den Apigee-Support wenden, um den Wert des Verweises zu ändern.

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 Truststore direkt angeben, müssen Sie sich an den Apigee-Support wenden.

Als dritte Option ist die Verwendung von Ablaufvariablen vorgesehen:

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

Mit Ablaufvariablen können Sie den Schlüsselspeicher oder Truststore wie Verweise aktualisieren. Weitere Informationen finden Sie unter Ablaufvariablen zur dynamischen Festlegung von TLS/SSL-Werten verwenden.

Informationen zur TLS-Konfiguration

Alle Apigee-Kunden, sowohl zahlende als auch solche in der Probephase, haben die vollständige Kontrolle über die Konfiguration der Zielendpunkte/Zielserver. Darüber hinaus haben zahlende Apigee-Kunden die vollständige Kontrolle über TLS-Attribute.

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 TLS für einen Zielendpunkt/Zielserver konfigurieren, sollten Sie vor der Konfiguration entscheiden, 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 selbst signierte Zertifikate, von einer vertrauenswürdigen Zertifizierungsstelle signierte Zertifikate oder Zertifikate, die im Rahmen von bidirektionaler TLS-Authentifizierung (auch gegenseitige TLS oder mTLS genannt) 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 die Referenz im Zielserver/Zielendpunkt, um den neuen Schlüsselspeicher 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 die Referenz auf Ihrem Zielserver/Zielendpunkt, um den neuen Truststore zu verwenden.

Zusammenfassung der Methoden zum Aktualisieren eines abgelaufenen Zertifikats

Die Methode, mit der Sie den Namen des Schlüsselspeichers und des Truststore im Zielendpunkt/Zielserver angeben, bestimmt, wie Sie das Zertifikat aktualisieren. Sie können Folgendes angeben:

  • Verweise
  • Direkte Namen
  • Ablaufvariablen

Jede dieser Methoden hat unterschiedliche Auswirkungen auf den Aktualisierungsprozess, wie in folgender Tabelle dargestellt:

Konfigurationstyp Zertifikat aktualisieren/ersetzen Nutzung
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 des alten Alias.

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

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

Sie müssen den Apigee-Support nicht kontaktieren.
Ablaufvariable 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 bei jeder Anfrage die aktualisierte Ablaufvariable mit dem Namen des neuen Schlüsselspeichers, Alias oder Truststore.

Sie müssen den Apigee-Support nicht kontaktieren.
Direkt Erstellen Sie einen neuen Schlüsselspeicher, einen Alias oder einen Truststore. Stellen Sie den Proxy noch einmal bereit.
Direkt Löschen Sie den Schlüsselspeicher oder Truststore und erstellen Sie ihn noch einmal mit demselben Namen. API-Anfragen schlagen fehl, bis der neue Schlüsselspeicher und der neue Alias festgelegt sind.

Wenn der Schlüsselspeicher für das bidirektionale TLS (auch gegenseitige TLS oder mTLS genannt) zwischen Apigee und dem Backend-Dienst verwendet wird, wenden Sie sich an den Apigee-Support, um die Nachrichtenprozessoren erneut zu starten.
Direkt Laden Sie nur für Truststores ein neues Zertifikat in den Truststore hoch. Wenden Sie sich an den Apigee-Support, um die Message Processors neu zu starten.