Änderungen in Edge for Private Cloud 4.53.01

Änderungen im Überblick

In Edge for Private Cloud 4.53.01 wurden mehrere Änderungen eingeführt, die die Sicherheit der Plattform verbessern. Außerdem wurden aktualisierte Versionen der erforderlichen Software und Bibliotheken integriert. Diese Änderungen betreffen die folgenden Richtlinientypen:

• OAS-Validierungsrichtlinie (OpenAPI Specification)
• Richtlinien, die JSONPath-Abfragen unterstützen
• Java-Callout-Richtlinien, die auf eingestellten Bibliotheken basieren.
• OpenLDAP
• Änderungen am Kryptografieanbieter

Sie können auch das Tool zur Erkennung von Änderungen verwenden, um Änderungen an den Proxys, freigegebenen Abläufen oder anderen Artefakten in Ihrem Cluster zu erkennen, die aufgrund dieses Upgrades zu Störungen führen können.

Detaillierte Beschreibung der Änderungen

In diesem Abschnitt werden die Änderungen in Version 4.53.01 beschrieben, die Ihre Arbeitsabläufe während oder nach dem Upgrade beeinträchtigen können. Außerdem werden Methoden zur Identifizierung potenzieller Problembereiche sowie Methoden zur Risikominderung oder Problemumgehungen behandelt.

OAS-Validierungsrichtlinie (OpenAPI-Spezifikation)

Kontext

Mit der OASValidation-Richtlinie werden eingehende Anfragen oder Antworten anhand der in der OpenAPI 3.0-Spezifikation (JSON oder YAML) definierten Regeln validiert. In Edge for Private Cloud 4.53.01 wurden Verbesserungen an der OAS-Richtlinie (OpenAPI-Spezifikation) vorgenommen, die sich auf eine strengere und genauere Validierung von API-Antworttexten konzentrieren.

Änderungen

In Edge for Private Cloud 4.53.01 werden zwei wichtige Änderungen an der Art und Weise eingeführt, wie die OAS-Richtlinie API-Antworten validiert. Dadurch wird eine engere Abstimmung mit Ihrer OpenAPI-Spezifikation erreicht:

• Szenario 1:
  • Bisheriges Verhalten:Wenn für Ihre OpenAPI-Spezifikation ein Antworttext erforderlich war, die tatsächliche Antwort vom Ziel oder der Upstream-Richtlinie jedoch keinen enthielt, wurde dies von der Richtlinie nicht als Validierungsfehler gekennzeichnet.
  • Aktuelles Verhalten: Die Richtlinie gibt in diesem Szenario jetzt korrekt einen Validierungsfehler zurück (z. B. defines a response schema but no response body found), der auf eine Abweichung zwischen der erwarteten und der tatsächlichen Antwort hinweist.
• Szenario 2:
  • Bisheriges Verhalten:Wenn in Ihrer OpenAPI-Spezifikation explizit angegeben war, dass kein Antworttext erwartet wurde, die tatsächliche Antwort vom Ziel oder der Upstream-Richtlinie jedoch einen Text enthielt, führte die Richtlinie nicht zu einem Fehler.
  • Aktuelles Verhalten: Die Richtlinie führt in diesem Szenario jetzt zu einem Fehler (z. B. No response body is expected but one was found), damit die Antworten dem angegebenen Schema entsprechen.

Problembehebung

Ermitteln Sie mithilfe des Tools zur Änderungserkennung oder durch manuelle Überprüfung alle Proxys oder freigegebenen Abläufe, die von der Aktualisierung betroffen sein könnten. Suchen Sie nach Proxys, bei denen eine der folgenden Bedingungen zutrifft:

• Die OASValidation-Richtlinie ist mit einem Source-Tag konfiguriert, das auf response gesetzt ist.
• Die OAS-Validierungsrichtlinie validiert eine Antwort von einer anderen Richtlinie, die eine Antwort generiert.

Wenn Sie das Tool verwenden, wird die Ausgabe im folgenden Format generiert:

Eine detaillierte Erläuterung der Spalten in der Ausgabetabelle finden Sie im Abschnitt Toolausgabe verstehen.

Wenn ein Proxy oder ein freigegebener Ablauf identifiziert wurde, achten Sie darauf, dass die Antwort und Ihre OAS-Spezifikation hinsichtlich des Vorhandenseins oder Fehlens eines Antworttexts übereinstimmen. Sie können Standard-Apigee-Traces verwenden, um Ihre Traffic-Muster zu prüfen. Wenn das Ziel intermittierend eine Antwort zurückgibt, verwenden Sie andere Richtlinien, um die Antwort zu validieren, bevor sie an die OAS-Validierungsrichtlinie übergeben wird.

• Wenn in Ihrer OAS-Spezifikationsdatei ein Antworttext definiert ist, muss die Antwort von der Ziel- oder Upstream-Richtlinie immer einen Antworttext enthalten.
• Wenn in Ihrer OAS-Spezifikationsdatei kein Antworttext definiert ist, darf die Ziel- oder Upstream-Richtlinie keinen senden.

Aktualisieren Sie die OAS-Validierungsrichtlinie oder Ihr Zielverhalten nach Bedarf, bevor Sie das Upgrade auf Private Cloud 4.53.01 durchführen. Sie sollten solche identifizierten Arbeitsabläufe zuerst in Ihren Nicht-Produktionsumgebungen validieren, um das Risiko von Unterbrechungen während des Upgrades des Produktionsclusters zu minimieren.

JSON-Pfad

Kontext

In Edge for Private Cloud 4.53.01 wurde die Verwendung von JSON-Pfadausdrücken in verschiedenen Richtlinien geändert. JSONPath-Ausdrücke können in Richtlinien wie ExtractVariable, RegularExpressionProtection und Data masking verwendet werden, um JSON-Inhalte zu parsen oder Werte in Variablen zu speichern. JSONPath-Ausdrücke können auch in der allgemeinen Nachrichtenvorlagenerstellung verwendet werden, um Variablen während der Proxy-Ausführung dynamisch durch Werte zu ersetzen. Die neuen JSONPath-Ausdrücke und ‑Formate entsprechen den neuesten JSON-Ausdrucksstandards.

Änderungen

Es ist wichtig, vorhandene API-Proxys/freigegebene Abläufe auf Richtlinien zu prüfen, in denen JSONPath-Ausdrücke verwendet werden. Dazu gehören unter anderem die Richtlinie „Variablen extrahieren“, die Richtlinie „Schutz vor regulären Ausdrücken“ oder eine beliebige Richtlinie mit Nachrichtenvorlage, die JSONPath verwendet.

Die folgenden JSON-Eingaben werden verwendet, um die Änderungen zu erläutern:

{
  "store": {
    "book": [
      {"category": "reference", "author": "Nigel Rees", "price": 8.95},
      {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
      {"category": "fiction", "author": "Herman Melville", "price": 8.99}
    ],
    "bicycle": {
      "color": "red",
      "book": [
        {"author": "Abc"}
      ]
    }
  }
}

1. Verhaltensänderung bei JSONPath-Wildcard [*] für Objektwerte

   Das Verhalten des Platzhalters [*] wurde geändert, wenn er für den Zugriff auf alle unmittelbaren Werte eines JSON-Objekts verwendet wird. Bisher wurden mit $.object[*] die unmittelbaren Werte in einem einzelnen JSON-Objekt zurückgegeben. Mit den aktualisierten Bibliotheken ist die Ausgabe jetzt ein Array mit diesen Werten.

   Zum Beispiel $.store[*]:

   Bisheriges Verhalten:

   {
     "bicycle": {
       "color": "red",
       "book": [{"author": "Abc"}]
     },
     "book": [
       {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
       {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
       {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
     ]
   }
   

   Vor der Änderung:

   [
     [
       {"category": "reference", "author": "Nigel Rees", "price": 8.95},
       {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
       {"category": "fiction", "author": "Herman Melville", "price": 8.99}
     ],
     {
       "color": "red",
       "book": [{"author": "Abc"}]
     }
   ]
   

   Aktion:

   Ändern Sie den JSONPath-Ausdruck so, dass er nur auf das übergeordnete Objekt verweist (z. B. $.store), um direkt auf die zuvor abgerufenen Elemente zu verweisen.

2. Fehler durch nachgestellten Punkt (.) in JSONPath-Pfaden

   JSONPath-Ausdrücke werden strenger validiert. Bisher wurden Pfade, die mit einem ungültigen nachgestellten Punkt enden (z. B. $.path.to.element.), stillschweigend ignoriert und die Abfrage gab weiterhin ein Ergebnis zurück, wenn das vorhergehende gültige Pfadsegment übereinstimmte. In der neuen Version werden solche fehlerhaften Pfade jetzt korrekt als ungültig erkannt und führen zu einem Fehler.

   Beispiel: $.store.book.

   Bisheriges Verhalten:

   [
     {"price":8.95,"category":"reference","author":"Nigel Rees"},
     {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
     {"price":8.99,"category":"fiction","author":"Herman Melville"}
   ]
   

   Vor der Änderung:

   ERROR: com.jayway.jsonpath.InvalidPathException - Path must not end with a '.' or '..'
   

   Alle vorhandenen Richtlinien, in denen JSONPath-Ausdrücke mit einem unbeabsichtigten nachgestellten Punkt verwendet werden, schlagen jetzt mit einem InvalidPathException fehl.

   Aktion:

   Entfernen Sie den nachgestellten Punkt aus allen JSONPath-Ausdrücken, die damit enden. Ändern Sie beispielsweise $.store.book. in $.store.book.

3. Änderung der Ausgabestruktur für den rekursiven Abstieg von JSONPath (..)

   Es gibt Änderungen bei der Rückgabe von Ergebnissen, wenn Sie den Operator (..) (rekursiver Abstieg) verwenden, um alle Vorkommen eines benannten Elements zu finden. Bisher wurden alle gefundenen Elemente in einer einzigen Liste zusammengefasst. Die aktualisierten Bibliotheken geben jetzt eine Liste von Listen zurück, wodurch die ursprüngliche Gruppierungsstruktur beibehalten wird, in der Elemente gefunden wurden, anstatt einer einzelnen flachen Liste.

   Beispiel: $..book

   Bisheriges Verhalten:

   [
     {"price":8.95,"category":"reference","author":"Nigel Rees"},
     {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
     {"price":8.99,"category":"fiction","author":"Herman Melville"},
     {"author":"Abc"}
   ]
   

   Vor der Änderung:

   [
     [
       {"category":"reference","author":"Nigel Rees","price":8.95},
       {"category":"fiction","author":"Evelyn Waugh","price":12.99},
       {"category":"fiction","author":"Herman Melville","price":8.99}
     ],
     [
       {"author":"Abc"}
     ]
   ]
   

   Aktion:

   Aktualisieren Sie die Logik für die Downstream-Verarbeitung, um die neue Struktur des verschachtelten Arrays zu berücksichtigen. Wahrscheinlich müssen Sie die äußere JSONArray durchlaufen und dann jede innere JSONArray, um auf die einzelnen Elemente zuzugreifen.

4. JSONPath-Indexierung nach Auswahl oder Filter mehrerer Elemente gibt leeres Array zurück

   Es gibt eine Verhaltensänderung, wenn ein Index (z. B. [0]) direkt nach einer Auswahl mit mehreren Elementen (z. B. [*]) oder einem Filter ([?(condition)]) angewendet wird. Bisher wurde bei solchen Ausdrücken versucht, das Element am angegebenen Index aus den kombinierten Ergebnissen auszuwählen. In der neuen Version geben diese Ausdrücke jetzt ein leeres Array ([]) zurück.

   Beispiel: $.store.book[*][0]

   Bisheriges Verhalten:

   {"category": "reference", "price": 8.95, "author": "Nigel Rees"}
   

   Vor der Änderung:

   []
   

   Aktion:

   Wenn Sie ein bestimmtes Element aus dem gefilterten Satz filtern und abrufen müssen, verarbeiten Sie das gefilterte Array, das von JSONPath zurückgegeben wird, z. B. $..book[?(@.category == 'fiction')], und übernehmen Sie dann [0] aus dem vorherigen Ergebnis.

5. Änderung der Ausgabe für negatives Array-Slicing in JSONPath

   In der neuen Version wurde das Verhalten von negativen Array-Slices geändert (z. B. [-2:], [-1:]). Bisher wurde bei der Anwendung eines negativen Slice auf ein Array (Elemente vom Ende des Arrays) in der alten Version fälschlicherweise nur ein einzelnes Element aus diesem Slice zurückgegeben. In der neuen Version wird jetzt korrekt eine Liste (Array) mit allen Elementen zurückgegeben, die in den angegebenen negativen Bereich fallen.

   Beispiel: $.store.book[-2:]

   Bisheriges Verhalten:

   {"price":12.99,"category":"fiction","author":"Evelyn Waugh"}
   

   Vor der Änderung:

   [
     {"category":"fiction","author":"Evelyn Waugh","price":12.99},
     {"category":"fiction","author":"Herman Melville","price":8.99}
   ]
   

   Aktion:

   Die nachgelagerte Verarbeitungslogik muss jetzt aktualisiert werden, um das zurückgegebene JSON-Array zu durchlaufen und die gewünschte Ausgabe zu erhalten.

6. JSONPath-Punkt muss vorangestellt werden

   Die Syntax für Elemente, auf die direkt über das Stammverzeichnis zugegriffen wird, wird strenger durchgesetzt. Wenn auf die Elemente direkt über den Stamm ohne vorangestellten Punkt zugegriffen wird (z. B. $propertyelement), gilt diese Syntax jetzt als Fehler und verhindert die Proxybereitstellung.

   Beispiel: $store

   {
     "bicycle": {
       "color": "red",
       "book": [{"author": "Abc"}]
     },
     "book": [
       {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
       {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
       {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
     ]
   }
   

   Aktuelles Verhalten:

   Proxy will fail to deploy.

   Aktion:

   Ändern Sie den JSONPath so, dass er den Punkt enthält: $.propertyName (Beispiel: $.store). Dadurch wird der Wert richtig abgerufen.

7. Dynamische JSONPath-Ausdrücke

   Achten Sie genau auf Richtlinien, in denen der JSONPath-Ausdruck selbst durch eine Variable bereitgestellt wird (z. B. {myJsonPathVariable} oder {dynamicPath}). Der Wert dieser Variablen muss ebenfalls anhand der oben beschriebenen potenziellen Verhaltensänderungen geprüft werden.

Problembehebung

Ermitteln Sie mithilfe des Tools zur Änderungserkennung oder durch manuelles Überprüfen Ihrer API-Proxys, welche Proxys oder freigegebenen Abläufe von der Aktualisierung betroffen sein könnten. Wenn Sie das Tool verwenden, wird in der Ausgabe der betroffene Proxy oder freigegebene Flow, die relevante Richtlinie und alle problematischen JSON-Pfade angegeben, wie im folgenden Beispiel zu sehen ist:

Eine detaillierte Erläuterung der Spalten in der obigen Ausgabetabelle finden Sie im Abschnitt Tool-Ausgabe verstehen.

Um das Risiko zu minimieren, ist eine umfassende Strategie erforderlich. Dazu gehört, den geeigneten Aktualisierungspfad auszuwählen und die erforderliche Korrektur für erkannte JSONPath-Ausdrücke anzuwenden.

Wählen Sie die für Sie am besten geeignete Methode für den Upgrade-Pfad aus:

• Migration ohne Ausfallzeiten

  Bei dieser Strategie werden eine oder mehrere neue Umgebungen bereitgestellt, damit Sie separate Nachrichtenprozessorknoten damit verbinden können. Für solche Nachrichtenknoten kann die Version 4.53.01 installiert werden und sie können Proxys mit modernen JSONPath-Ausdrücken haben. Sie können während des Upgrades verwendet und nach Abschluss des Upgrades außer Betrieb genommen werden. Diese Strategie ist nahtlos, erfordert jedoch die vorübergehende Beschaffung zusätzlicher Message-Processor-Knoten, um ein reibungsloses Upgrade zu ermöglichen. Details:

  • Erstellen Sie eine neue Umgebung und fügen Sie dieser neuen Umgebung neue Message-Processor-Knoten der Version 4.53.01 hinzu.
  • Laden Sie das Proxy-Bundle für die betroffenen Proxys in die neue Umgebung hoch, wenden Sie die im Abschnitt zur Fehlerbehebung beschriebenen erforderlichen Korrekturen an und stellen Sie das aktualisierte Proxy-Bundle in der neuen Umgebung bereit.
  • Leiten Sie den Traffic in die neue Umgebung um und heben Sie die Bereitstellung der betroffenen Proxys in der alten Umgebung auf.
  • Führen Sie ein Upgrade der ursprünglichen Message Processor-Knoten auf Version 4.53.01 durch. Stellen Sie Proxys mit Korrekturen für JSONPath in der ursprünglichen Umgebung bereit.
  • Leiten Sie den Traffic wieder an die alte Umgebung weiter. Diese hat jetzt Message-Prozessoren auf Version 4.53.01 und einen Proxy, der für neue JSONPath-Ausdrücke modernisiert wurde.
  • Löschen und deaktivieren Sie die neue Umgebung und die zugehörigen Knoten.
• Ausfallzeiten und Upgrade

  Bei dieser Strategie wird die Ausfallzeit für API-Proxys mit fehlerhaften JSONPath-Ausdrücken berücksichtigt. Dazu sind keine zusätzlichen Message Processor-Knoten erforderlich, aber der API-Traffic für betroffene Proxys wird unterbrochen.

  • Identifizieren Sie die betroffenen Proxys mit den betroffenen Richtlinien und erstellen Sie eine neue Überarbeitung für alle betroffenen Proxys.
  • Nehmen Sie die erforderlichen Korrekturen vor, indem Sie die im Abschnitt zur Fehlerbehebung beschriebenen Korrekturen in einer neuen Überarbeitung des Proxys implementieren. Stellen Sie es noch nicht bereit.
  • Sorgen Sie für Ausfallzeiten für den/die betroffenen Proxy(s).
  • Aktualisieren Sie alle Message Processors auf Edge for Private Cloud Version 4.53.01. Hinweis: Die vorhandenen Proxys funktionieren möglicherweise nicht auf den neu aktualisierten Message Processors.
  • Wenn alle Message Processors auf Edge for Private Cloud Version 4.53.01 aktualisiert wurden , stellen Sie die neu erstellte Proxy-Revision mit dem korrigierten JSONPath-Ausdruck bereit.
  • Traffic auf solchen Proxys fortsetzen
• Proxy vor dem Upgrade neu gestalten

  Sie können den Proxy selbst neu gestalten, bevor Sie auf Edge for Private Cloud 4.53.01 aktualisieren. Anstatt auf bestimmte JSON-Pfadausdrücke zu setzen, können Sie dasselbe Ergebnis mit einer anderen Methode erzielen.

  Wenn Sie beispielsweise eine Richtlinie zum Extrahieren von Variablen mit einem JSON-Pfad verwenden, können Sie die Richtlinie durch eine JavaScript-Richtlinie ersetzen, die ähnliche Daten extrahiert, bevor Sie auf die neuere Version aktualisieren. Nach dem Upgrade können Sie Ihren Proxy wieder so ändern, dass JSON-Pfade mit neueren Formaten verwendet werden.

JavaCallout-Änderungen

Kontext

In Edge for Private Cloud 4.53.00 und früher gab es ein Verzeichnis namens deprecated ($APIGEE_ROOT/edge-message-processor/lib/deprecated), das eine Reihe von JAR-Bibliotheken enthielt. Diese Bibliotheken waren für die Verwendung in Java-Code in der JavaCallout-Richtlinie verfügbar und konnten direkt oder indirekt von Ihrem benutzerdefinierten Java-Code verwendet werden.

Änderungen

Das eingestellte-Verzeichnis wurde in Edge für die private Cloud-Version 4.53.01 entfernt. Wenn Ihr Java-Code auf solchen Bibliotheken basiert, schlagen Proxys, die solche Java-Callouts verwenden, fehl, wenn Message-Prozessoren auf Version 4.53.01 aktualisiert werden. Um solche Fehler zu vermeiden, führen Sie die folgenden Schritte aus, bevor Sie die Message-Prozessoren auf Version 4.53.01 aktualisieren.

Problembehebung

1. Überprüfen Sie Ihre Java-Callout-Richtlinien und zugehörigen JAR-Dateien mit dem Tool zur Änderungserkennung oder manuell. Prüfen Sie, ob in einer der Richtlinien auf Bibliotheken verwiesen wird, die sich im Verzeichnis „deprecated“ Ihrer aktuellen Message-Prozessoren befinden.

   Wenn Sie das von Apigee bereitgestellte Tool für die oben genannten Erkennungen verwenden, wird ein Bericht wie in der folgenden Tabelle generiert . Sie bezieht sich insbesondere auf Richtlinien, die auf JAR-Dateien im Verzeichnis $APIGEE_ROOT/edge-message-processor/lib/deprecated älterer Edge for Private Cloud-Versionen verweisen.

   Das Tool generiert Berichte im folgenden Format:

   Organisation	Umgebung	Name des Artefakts	Artefakttyp	Überarbeitung	Richtlinienname	Richtlinientyp	Art der Auswirkungen	Wirkungsspezifisches Feld	Wahrscheinlichkeit der Auswirkungen	Dokumentation
   org1	Keine	Keine	org-level-jar	Keine	Keine	java-callout	Veraltete Bibliothek für simple-javacallout-o1-jar-1.jar erkannt	['Detected use of class org.apache.commons.io.FileUtils from commons-io-2.5.jar, 'Detected use of class org.apache.commons.io.input.XmlStreamReaderException from commons-io-2.5.jar']	Hoch	JavaCallout-Änderungen
   org3	env3	Keine	env-level-jar	Keine	Keine	java-callout	Veraltete Bibliothek für fat-javacallout-e3-jar-1.jar erkannt	['Detected use of class org.apache.http.impl.auth.NTLMSchemeFactory from httpclient-4.5.2.jar'] (Verwendung der Klasse org.apache.http.impl.auth.NTLMSchemeFactory aus httpclient-4.5.2.jar erkannt)	Hoch	JavaCallout-Änderungen
   org1	env1	p1	proxy-level-jar	1	Keine	java-callout	Veraltete Bibliothek für simple-javacallout-p1-jar-1.jar erkannt	['Detected use of class org.apache.commons.lang3.builder.ToStringBuilder from commons-lang3-3.4.jar', 'Detected use of class org.apache.commons.lang3.Validate from commons-lang3-3.4.jar']	Hoch	JavaCallout-Änderungen

   Eine detaillierte Erläuterung der Spalten in der obigen Ausgabetabelle finden Sie im Abschnitt Tool-Ausgabe verstehen.

2. Nachdem Sie solche veralteten Bibliotheken identifiziert haben , können Sie das Problem mit einer der folgenden Methoden beheben.
   • Ressourcenplatzierung (empfohlen, wenn Sie nur wenige JAR-Dateien / Bibliotheken aus dem eingestellten Verzeichnis haben, auf die von den Java-Callout-JAR-Dateien verwiesen wird)
     • Laden Sie die identifizierten eingestellten JARs als Ressource auf der gewünschten Ebene hoch: API-Proxy-Überarbeitung, Umgebung oder Organisation.
     • Fahren Sie wie gewohnt mit dem Apigee-Software-Upgrade fort.
   • Manuelle Platzierung (empfohlen, wenn Sie eine große Anzahl von JARs / Bibliotheken haben, auf die von den Java-Callout-JARs verwiesen wird)
     • Erstellen Sie auf jedem Knoten des Nachrichtenprozessors ein neues Verzeichnis mit dem Namen external-lib unter dem Pfad $APIGEE_ROOT/data/edge-message-processor/.
     • Kopieren Sie die identifizierten JARs aus dem eingestellten Verzeichnis cp $APIGEE_ROOT/edge-message-processor/lib/deprecated/some.jar $APIGEE_ROOT/data/edge-message-processor/external-lib/some.jar in das Verzeichnis external-lib:
     • Achten Sie darauf, dass das Verzeichnis und die zugrunde liegenden JAR-Dateien vom Apigee-Nutzer gelesen werden können: chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
     • Fahren Sie wie gewohnt mit dem Apigee-Software-Upgrade fort.

OpenLDAP-Änderung

Kontext

OpenLDAP kann in Edge Private Cloud sowohl für die Authentifizierung als auch für die Autorisierung verwendet werden. In Edge for Private Cloud 4.53.01 wurde die von Apigee bereitgestellte OpenLDAP-Software von Version 2.4 auf Version 2.6 aktualisiert.

Änderungen

In OpenLDAP 2.6 ist der Relative Distinguished Name (RDN) auf etwa 241 Byte/Zeichen begrenzt. Dieses Limit ist ein fester Grenzwert, der nicht geändert werden kann.

• Bei Einträgen mit zu großen relativen Distinguished Names (RDNs) treten Replikations- oder Importfehler auf.
• Wenn Sie versuchen, Entitäten wie Organisationen, Umgebungen, benutzerdefinierte Rollen oder Berechtigungen zu erstellen, wird möglicherweise die Fehlermeldung "message": "[LDAP: error code 80 - Other]" angezeigt.
• Alle DNs, die länger als 241 Byte sind, sind betroffen. Solche DNs verhindern ein erfolgreiches Upgrade der Apigee OpenLDAP-Software. Sie müssen Gegenmaßnahmen für solche Elemente ergreifen, bevor Sie mit dem Upgrade fortfahren können.

Im LDAP von Apigee hängen lange DNs in der Regel mit Berechtigungen zusammen, da sie durch Verketten mehrerer Entitäten erstellt werden. Solche Berechtigungseinträge sind besonders anfällig für Probleme bei der Aktualisierung.

Beispiel:

dn: cn=@@@environments@@@*@@@applications@@@*@@@revisions@@@*@@@debugsessions,ou=resources,cn=businessuser,ou=userroles,o=orgname,ou=organizations,dc=apigee,dc=com

Normalerweise haben Organisations-, Umgebungs- und Rollennamen eine Länge, sodass RDNs in LDAP kleiner als 241 Byte sind.

Problembehebung

Vor dem Upgrade auf Version 4.53.01:

Mit den folgenden Schritten können Sie prüfen, ob in Ihrem bestehenden LDAP 2.4-Cluster lange RDNs vorhanden sind.

1. LDAP-Daten extrahieren

Verwenden Sie den Befehl „ldapsearch“, um den definierten Namen (dn) zu finden, und leiten Sie die Ausgabe an eine Datei weiter:

ldapsearch -o ldif-wrap=no -b "dc=apigee,dc=com" -D "cn=manager,dc=apigee,dc=com" -H ldap://:10389 -LLL -x -w LDAP_PASSWORD dn > /tmp/DN.ldif

Prüfen Sie, ob die Datei „DN.ldif“ oben LDAP-Einträge enthält.

#2 – Lange RDNs identifizieren

Mit dem Tool zur Änderungserkennung wird eine generierte LDIF-Datei verwendet, um LDAP-RDNs zu identifizieren, die 241 Byte/Zeichen überschreiten.

Das Tool generiert Berichte im folgenden Format:

Eine detaillierte Erläuterung der Spalten in der obigen Ausgabetabelle finden Sie im Abschnitt Toolausgabe verstehen.

Wenn der obige Befehl keine Ausgabe erzeugt, überschreiten keine RDNs in der vorhandenen LDAP-Einrichtung 241 Byte/Zeichen. Sie können das Upgrade wie gewohnt durchführen.

Wenn der obige Befehl eine Ausgabe generiert, weist dies auf das Vorhandensein von RDNs hin, die 241 Byte/Zeichen überschreiten. Führen Sie für solche Elemente die Schritte zur Risikominderung aus, die in Schritt 3 beschrieben sind, bevor Sie mit dem Upgrade auf Edge for Private Cloud 4.53.01 fortfahren.

#3 – Lange RDNs verarbeiten

Wenn in Schritt 2 eine Ausgabe erfolgt, bedeutet dies, dass RDNs mit mehr als 241 Byte/Zeichen vorhanden sind. Führen Sie die folgenden Schritte zur Fehlerbehebung aus:

Prüfen Sie die LDAP-Einträge, die 241 Byte überschreiten.

• Wenn es sich um den Namen einer benutzerdefinierten Rolle, einer App, eines API-Produkts oder anderer Entitäten handelt, die hauptsächlich für den langen RDN verantwortlich sind, migrieren Sie zu einer alternativen Entität mit einem kürzeren Namen.
• Wenn der Organisationsname oder der Umgebungsname der Hauptgrund für den langen RDN ist, müssen Sie zu einer anderen Organisation oder Umgebung mit einem kürzeren Namen migrieren.

Wiederholen Sie die obigen Schritte, bis Ihr LDAP keine RDNs mehr enthält, die länger als 241 Byte sind. Sobald Sie diesen Status erreicht haben, fahren Sie wie gewohnt mit dem Upgrade der privaten Cloud-Version fort.

Änderungen am Kryptografieanbieter

Kontext

Diese Änderung wurde aus Edge for Private Cloud 4.53.00 übernommen. In Edge for Private Cloud 4.53.00 wurde der interne Kryptografieanbieter von Bouncy Castle (BC) auf Bouncy Castle FIPS (BCFIPS) aktualisiert, um FIPS-Unterstützung zu ermöglichen.

Änderungen

Wenn JavaCallout-Richtlinien auf dem ursprünglichen BC-Provider basieren, insbesondere bei Verwendung von Sicherheitsfunktionen, die im BCFIPS-Provider gehärtet wurden (z. B. Verwendung eines gemeinsamen Schlüsselpaars für Verschlüsselung und Signierung), müssen solche JavaCallout-Richtlinien modernisiert werden. JavaCallout-Richtlinien, die versuchen, den Bouncy Castle-Kryptografieanbieter mit dem Namen BC zu laden, können fehlschlagen, da sich der Standardanbieter geändert hat. Solche Richtlinien, die den BC-Anbieter verwenden, können später fehlschlagen. Benutzerdefinierte Implementierungen, die auf dem alten BC-Anbieter basieren, sind nicht mehr zugänglich und müssen überprüft und neu implementiert werden.

Problembehebung

Die empfohlene Problemumgehung besteht darin, den BCFIPS-Anbieter zu verwenden. Benutzerdefinierte JavaCallout-Implementierungen, die auf dem alten Anbieter basieren, müssen überprüft und mit dem Bouncy Castle FIPS-Anbieter neu implementiert werden. Auf diesen kann mit dem String „BCFIPS“ zugegriffen werden.

Tool zur Änderungserkennung

Es wurde ein Tool zur Änderungserkennung entwickelt, um Apigee-Proxys, ‑Richtlinien und ‑Shared Flows zu identifizieren, die während und nach der Umstellung auf Edge for Private Cloud 4.53.01 betroffen sein könnten. Mit diesem Tool wird ein Bericht mit Details zu bereitgestellten Proxys, freigegebenen Abläufen und OpenLDAP-Instanzen generiert, die von den Änderungen betroffen sind. Außerdem werden Links zu Anleitungen und Strategien bereitgestellt, die für die ermittelten Proxys oder freigegebenen Abläufe relevant sind.

Vorbereitung

1. Für die Ausführung dieses Tools ist ein RHEL-basierter Computer erforderlich.
2. JRE 8 muss auf der Host-VM installiert und richtig konfiguriert sein, damit die Skripts des Tools ausgeführt werden können.
3. Für das Tool ist der richtige Endpunkt (URL) des Management-Servers sowie gültige Administratoranmeldedaten für die Authentifizierung und den Datenabruf erforderlich.
4. Das Tool benötigt Zugriff auf ein bestimmtes Arbeitsverzeichnis (z.B./tmp), um Bundles zu extrahieren, Logs zu generieren und die Ausgabe zu speichern. Achten Sie darauf, dass in diesem Verzeichnis ausreichend Speicherplatz und die entsprechenden Lese-/Schreibberechtigungen vorhanden sind.
5. Das Tool benötigt die LDIF-Datei, die mit dem Befehl ldapsearch im Abschnitt OpenLDAP change – Extract LDAP data (OpenLDAP-Änderung – LDAP-Daten extrahieren) erstellt wurde, um die langen RDNs mit mehr als 241 Zeichen / Bytes zu erkennen.

Tool ausführen

Nachdem alle oben aufgeführten Voraussetzungen erfüllt sind, laden Sie das Tool herunter und geben Sie den Nutzernamen und das Passwort von Apigee an, mit denen Sie auf das Apigee-Repository zugreifen. Extrahieren Sie das heruntergeladene Archiv.

curl -u uName:pWord https://software.apigee.com/apigee/change-detector/change-detector-for-4.53.01_1.0.0.zip -o /tmp/change-detector-for-4.53.01_1.0.0.zip

unzip /tmp/change-detector-for-4.53.01_1.0.0.zip

Nachdem der Download abgeschlossen ist, können Sie mit dem folgenden Befehl alle verfügbaren Optionen für das Tool aufrufen:

./change-detector --help

Verwenden Sie den folgenden Befehl, um das Tool auszuführen, und ersetzen Sie die Platzhalter durch Ihre Informationen:

export APIGEE_PASSWORD=[your_password]
./change-detector --username [your_username] --mgmt-url [MGMT url]

Führen Sie den folgenden Befehl aus, um die großen LDAP-Einträge mit relativen Distinguished Names (RDN) zu erkennen:

./change-detector --username [your_username] --mgmt-url [MGMT url] --ldif-file [LDIF_file]

Das Tool generiert eine Ausgabe im JSON- oder CSV-Format, die direkt verwendet oder in ein für Menschen lesbares Tool wie Google Sheets importiert werden kann.

Tool-Ausgabe verstehen

Organisation

Er verweist auf den Namen der Organisation, in der sich das Artefakt befindet. Bei OpenLDAP-Änderungen ist das None.

Umgebung

Die spezifische Umgebung (z.B. Entwicklung, Test, Produktion) innerhalb der Organisation. Bei OpenLDAP-Änderungen ist das None.

Bei Änderungen an Java-Callouts ist dieses Feld None, wenn Artifact Type=env-level-jar.

Name des Artefakts

In diesem Feld wird der Name des Proxys/freigegebenen Ablaufs angegeben. Bei einer OpenLDAP-Änderung wird in diesem Feld die LDAP-Entität des RDN angezeigt.

Bei Änderungen an Java-Callouts ist dieses Feld None, wenn Artifact Type=env-level-jar oder org-level-jar.

Artefakttyp

• Bei Änderungen an OAS und JSON wird in dieser Spalte der Typ des Artefakts, Proxy oder Shared Flow angegeben.
• Für die Änderung des Java-Callout enthält diese Spalte Details zum Ort oder zur Ebene, an der die betroffene JAR-Datei hochgeladen wird. Ressourcen (JARs) können auf drei Ebenen gespeichert werden: org-level, env-level, proxy-level.
• Bei der OpenLDAP-Änderung gibt dieses Feld die im Tool verwendete LDIF-Datei an.

Überarbeitung

Sie verweist auf die bereitgestellte Version des betroffenen Proxys/freigegebenen Ablaufs. Bei OpenLDAP-Änderungen ist es None.

Richtlinienname

Der Name der spezifischen Richtlinie, die als potenzielles Problem identifiziert wurde. Bei OpenLDAP-Änderungen ist es None.

Richtlinientyp

Sie verweist auf den Typ der Richtlinie. Bei OpenLDAP-Änderungen ist es None.

Art der Auswirkungen

• In diesem Feld wird der spezifische Typ der Änderung beschrieben, die in einem Proxy oder freigegebenen Ablauf erkannt wurde.
• Bei der Änderung von Java-Callouts, der Erkennung von Änderungen im Zusammenhang mit Java-Callouts, verweist das Tool in dieser Spalte auf den betroffenen Java-Callout, der Verweise auf die JAR-Dateien im Verzeichnis $APIGEE_ROOT/edge-message-processor/lib/deprecated älterer Versionen von Edge for Private Cloud hat.

deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR

• Bei OpenLDAP-Änderungen wird in diesem Feld angezeigt, ob der RDN einer LDAP-Entität mehr als 241 Byte oder Zeichen umfasst.

Bestimmtes Feld beeinflussen

• Bei einer Änderung der OAS ist dieses Feld der Name der Variable, die im Source-Tag der Richtlinie verwendet wird.
• Bei JSON-Änderungen wird in diesem Feld der genaue JSONPath-Ausdruck oder das Element angezeigt, das als potenzielles Problem gekennzeichnet wurde.
• Bei der Änderung des Java-Callout enthält dieses Feld die Details der genauen Klassen und den Namen des entsprechenden JAR (im $APIGEE_ROOT/edge-message-processor/lib/deprecated-Verzeichnis älterer Private Cloud-Versionen), das vom betroffenen JavaCallout-JAR verwendet/referenziert wird. Dies führt zu Fehlern beim Upgrade auf Version 4.53.01, wenn keine Maßnahmen ergriffen werden.

 ['Detected use of class CLASS_NAME_1 from JAR_NAME_1',
    Detected use of class CLASS_NAME_2 from JAR_NAME_2', 
  .. , .. , ]

• Bei OpenLDAP-Änderungen wird in diesem Feld der RDN der LDAP-Entität angezeigt, der mehr als 241 Byte oder Zeichen umfasst.

Sicherheit der Auswirkungen

• Dieses Feld gibt an, mit welcher Wahrscheinlichkeit das Tool ein bestimmtes Element erkannt hat. Die Werte für diese Spalte können entweder High (Hoch) oder Medium (Mittel) sein. Möglicherweise werden später weitere Werte hinzugefügt.

  Ein hoher Wert bedeutet, dass das Tool eine sehr hohe Wahrscheinlichkeit dafür ermittelt hat, dass das Element nach dem Upgrade auf Version 4.53.01 dazu führt, dass die Anwendung nicht mehr funktioniert. Ein Medium-Wert gibt an, dass das Tool sich bei der Erkennung nicht sicher ist und weitere Strategien erforderlich wären, um eine Entscheidung zu treffen. Sie könnten beispielsweise einen Trace erfassen, um aufgelöste Variablen während der Proxy-Ausführung zu beobachten.

• Bei Erkennungen im Zusammenhang mit JavaCallout- und OpenLDAP-Änderungen ist der Wert für die Spalten zur Wahrscheinlichkeit der Auswirkungen immer Hoch.

Dokumentation

Diese Spalte enthält einen Hyperlink zur Apigee-Dokumentation (relevante Abschnitte dieses Artikels), in der das Problem und die Schritte zur Behebung beschrieben werden.