Modifiche in Edge for Private Cloud 4.53.01

Panoramica delle modifiche

Edge for Private Cloud 4.53.01 ha introdotto diverse modifiche che migliorano il livello di sicurezza della piattaforma, incorporando versioni aggiornate di software/librerie. Queste modifiche interessano:

  • Norme di convalida OAS (specifica OpenAPI)
  • Policy che supportano le query JSONPath
  • Norme di callout Java che si basano su librerie ritirate
  • OpenLDAP

Questa sezione descrive vari tipi di modifiche introdotte nella versione 4.53.01 che possono interrompere i tuoi flussi di lavoro durante o dopo l'upgrade. Vengono trattati anche i metodi per identificare le potenziali aree problematiche e le metodologie di mitigazione o soluzioni alternative.

Norme di convalida OAS (specifica OpenAPI)

Contesto

La policy di convalida OAS convalida le richieste o le risposte in entrata in base alle regole definite nella specifica OpenAPI 3.0 (JSON o YAML). Edge for Private Cloud 4.53.01 offre miglioramenti al criterio OAS (OpenAPI Specification), concentrandosi su una convalida più rigorosa e accurata dei corpi delle risposte API.

Modifiche

Edge for Private Cloud 4.53.01 introduce due importanti modifiche al modo in cui il criterio OAS convalida le risposte API, garantendo un allineamento più stretto con la specifica OpenAPI:

  • Scenario 1:
    • Comportamento precedente:se la tua specifica OpenAPI richiedeva un corpo della risposta, ma la risposta effettiva della policy di destinazione o upstream non lo includeva, la policy non lo segnalava come errore di convalida.
    • Comportamento attuale: in questo scenario, la norma restituirà ora correttamente un errore di convalida (ad esempio defines a response schema but no response body found), indicando una mancata corrispondenza tra la risposta prevista e quella effettiva.
  • Scenario 2:
    • Comportamento precedente:se la specifica OpenAPI indicava esplicitamente che non era previsto alcun corpo della risposta, ma la risposta effettiva della norma di destinazione o upstream includeva un corpo, la norma non avrebbe generato un errore.
    • Comportamento attuale: in questo scenario, la norma ora comporterà un errore (ad esempio: No response body is expected but one was found), garantendo che le risposte rispettino rigorosamente lo schema specificato.

Attenuazione

Identifica eventuali proxy o flussi condivisi in cui il criterio di convalida OAS è configurato con un tag Source impostato su response o quelli che convalidano la risposta di qualsiasi altro criterio che genera una risposta.

Una volta identificato un flusso proxy/condiviso, assicurati che la risposta e la specifica OAS siano allineate. La risposta deve essere rigorosamente in linea con la specifica OpenAPI in merito alla presenza o all'assenza di un corpo della risposta. Puoi utilizzare la traccia Apigee standard per esaminare i pattern di traffico. Se la destinazione restituisce una risposta in modo intermittente, utilizza altre norme per convalidarla prima delle norme OAS

  • Se il file di specifica OAS definisce un corpo della risposta, la risposta della policy di destinazione o upstream deve sempre fornirne uno.
  • Se il file di specifica OAS non definisce un corpo della risposta, la policy di destinazione o upstream non deve inviarne uno.

Aggiorna le norme di convalida OAS o il comportamento target in base alle necessità prima di tentare l'upgrade a Private Cloud 4.53.01. Devi convalidare i flussi di lavoro identificati negli ambienti non di produzione per ridurre al minimo il rischio di interruzioni durante l'upgrade del cluster di produzione.

Percorso JSON

Contesto

Edge for Private Cloud 4.53.01 ha introdotto modifiche al modo in cui vengono utilizzate le espressioni del percorso JSON in varie policy. Le espressioni JSONPath possono essere utilizzate in criteri come ExtractVariable, RegularExpressionProtection e Data masking per analizzare i contenuti JSON o archiviare i valori nelle variabili. Le espressioni JSONPath possono essere utilizzate anche nei modelli di messaggi generali per sostituire le variabili con valori in modo dinamico durante l'esecuzione del proxy. I nuovi formati e le nuove espressioni JSONPath seguono gli standard più recenti per le espressioni JSON.

Modifiche

È importante esaminare i proxy API/flussi condivisi esistenti per verificare la presenza di norme che utilizzano espressioni JSONPath. Ciò include, a titolo esemplificativo, la policy Estrai variabili, la policy Protezione espressioni regolari o qualsiasi policy con un modello di messaggio che utilizza JSONPath.

Il seguente input JSON viene utilizzato per spiegare le modifiche:

{
  "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. Modifica del comportamento del carattere jolly JSONPath [*] per i valori degli oggetti

    Il comportamento del carattere jolly [*] è stato modificato quando viene utilizzato per accedere a tutti i valori immediati di un oggetto JSON. In precedenza, $.object[*] restituiva i valori immediati racchiusi in un singolo oggetto JSON. Con le librerie aggiornate, l'output è ora un array contenente questi valori.

    Ad esempio, $.store[*]:

    Comportamento precedente: 
    {
  "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"}
  ]
}
    Comportamento attuale: 
    [
  [
    {"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"}]
  }
]
    Azione:

    Modifica l'espressione JSONPath in modo da scegliere come target semplicemente l'oggetto principale (ad esempio $.store) per scegliere come target direttamente gli elementi recuperati in precedenza.

  2. Il punto finale JSONPath (.) nei percorsi causa un errore

    Esiste una convalida più rigorosa per le espressioni JSONPath. In precedenza, i percorsi che terminavano con un punto finale non valido (ad esempio $.path.to.element.) venivano ignorati automaticamente e la query restituiva comunque un risultato se il segmento di percorso valido precedente corrispondeva. Con la nuova versione, questi percorsi non validi vengono ora identificati correttamente come non validi e generano un errore.

    Ad esempio, $.store.book.

    Comportamento precedente: 
    [
  {"price":8.95,"category":"reference","author":"Nigel Rees"},
  {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
  {"price":8.99,"category":"fiction","author":"Herman Melville"}
]
    Comportamento attuale: 
    ERROR: com.jayway.jsonpath.InvalidPathException - Path must not end with a '.' or '..'

    Tutti i criteri esistenti che utilizzano espressioni JSONPath con un punto finale non intenzionale ora non funzioneranno e verrà visualizzato un InvalidPathException.

    Azione:

    Rimuovi il punto finale da qualsiasi espressione JSONPath che termina con un punto. Ad esempio, modifica $.store.book. in $.store.book.

  3. Modifica della struttura dell'output (..) di JSONPath recursive descent

    Sono state apportate modifiche al modo in cui vengono restituiti i risultati quando si utilizza l'operatore (..) (discesa ricorsiva) per individuare tutte le occorrenze di un elemento denominato. In precedenza, tutti gli elementi trovati venivano appiattiti in un unico elenco. Le librerie aggiornate ora restituiscono un elenco di elenchi, mantenendo la struttura di raggruppamento originale in cui sono stati trovati gli elementi, anziché un unico elenco piatto.

    Ad esempio, $..book

    Comportamento precedente: 
    [
  {"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"}
]
    Comportamento attuale: 
    [
  [
    {"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"}
  ]
]
    Azione:

    Aggiorna la logica di elaborazione downstream per tenere conto della nuova struttura dell'array nidificato. Probabilmente dovrai scorrere l'JSONArray esterno e poi ogni JSONArray interno per accedere ai singoli elementi.

  4. Indicizzazione JSONPath dopo la selezione di più elementi o il filtro restituisce un array vuoto

    Si verifica una modifica nel comportamento quando un indice (ad esempio [0]) viene applicato immediatamente dopo un selettore di più elementi (come [*]) o un filtro ([?(condition)]). In precedenza, queste espressioni tentavano di selezionare l'elemento all'indice specificato dai risultati combinati. Con la nuova versione, queste espressioni restituiranno un array vuoto ([]).

    Ad esempio, $.store.book[*][0]

    Comportamento precedente: 
    {"category": "reference", "price": 8.95, "author": "Nigel Rees"}
    Comportamento attuale: 
    []
    Azione:

    Se è necessario filtrare e poi ottenere un elemento specifico dal set filtrato, elabora l'array filtrato restituito da JSONPath, ad esempio $..book[?(@.category == 'fiction')], e poi prendi [0] dal risultato precedente.

  5. Modifica dell'output dello slicing negativo degli array JSONPath

    La nuova versione ha modificato il comportamento del sezionamento di array negativi (ad esempio: [-2:], [-1:]). In precedenza, quando si applicava una sezione negativa a un array (indicando gli elementi dalla fine dell'array), la vecchia versione restituiva erroneamente un solo elemento da quella sezione. La nuova versione ora restituisce correttamente un elenco (array) contenente tutti gli elementi che rientrano nell'intervallo negativo specificato.

    Ad esempio, $.store.book[-2:]

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

    La logica di elaborazione downstream deve ora essere aggiornata per scorrere l'array JSON restituito e ottenere l'output desiderato.

  6. JSONPath stricter preceding dot

    L'applicazione della sintassi per gli elementi a cui si accede direttamente dalla radice è più rigorosa. Quando si accede direttamente agli elementi dalla radice senza un punto precedente (ad esempio: $propertyelement), questa sintassi viene ora considerata un errore e impedirà il deployment del proxy.

    Ad esempio, $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"}
  ]
}

    Comportamento attuale:

    Proxy will fail to deploy.

    Azione:

    Modifica JSONPath in modo da includere il punto: $.propertyName (esempio: $.store). In questo modo, il valore verrà selezionato e recuperato correttamente.

  7. Espressioni JSONPath dinamiche

    Presta particolare attenzione alle norme in cui l'espressione JSONPath è fornita da una variabile (ad esempio {myJsonPathVariable} o {dynamicPath}). Il valore di queste variabili deve essere verificato anche in base ai potenziali cambiamenti di comportamento descritti in precedenza.

Attenuazione

Per mitigarli, è necessaria una strategia completa. Questo processo prevede la scelta del percorso di aggiornamento appropriato e l'applicazione della correzione necessaria per le espressioni JSONPath interrotte.

Scegli il metodo di percorso di upgrade più adatto a te:

  • Migrazione senza tempi di inattività

    Questa strategia prevede l'acquisizione di uno o più nuovi ambienti a cui collegare nodi di elaborazione dei messaggi separati. Questi nodi del processore di messaggi possono essere impostati per installare la versione 4.53.01 e avere proxy con espressioni JSONPath moderne. Questi possono essere utilizzati durante l'upgrade e possono essere ritirati al termine dell'upgrade. Questa strategia è trasparente, ma prevede l'approvvigionamento temporaneo di nodi di elaborazione dei messaggi aggiuntivi per supportare un upgrade senza problemi. Dettagli di seguito:

    • Crea un nuovo ambiente e aggiungi nuovi nodi di elaborazione dei messaggi della versione 4.53.01 a questo nuovo ambiente.
    • Carica il bundle del proxy per i proxy interessati nel nuovo ambiente e applica le correzioni necessarie spiegate nella sezione di correzione e implementa il bundle del proxy aggiornato nel nuovo ambiente.
    • Reindirizza il traffico al nuovo ambiente e annulla il deployment dei proxy interessati dal vecchio ambiente.
    • Esegui l'upgrade dei nodi del processore di messaggi originale alla versione 4.53.01. Esegui il deployment dei proxy che hanno correzioni per JSONPath nell'ambiente originale.
    • Sposta di nuovo il traffico nel vecchio ambiente, che ora dispone di processori di messaggi sulla versione 4.53.01 e di un proxy modernizzato per le nuove espressioni jsonpath.
    • Elimina e ritira il nuovo ambiente e i nodi associati.
  • Tempi di inattività e upgrade

    Questa strategia prevede l'acquisizione di tempi di inattività per i proxy API utilizzando espressioni di percorso JSON errate. Non è necessario procurarsi nodi di elaborazione dei messaggi aggiuntivi, ma causa interruzioni del traffico API per i proxy interessati.

    • Identifica i proxy interessati con le norme interessate e genera una nuova revisione per tutti i proxy interessati.
    • Applica le correzioni necessarie implementando quelle spiegate nella sezione di correzione in una nuova revisione del proxy. Non eseguire ancora il deployment.
    • Procurati tempi di inattività per il proxy o i proxy interessati.
    • Esegui l'upgrade di tutti i processori di messaggi a Edge per la versione 4.53.01 del cloud privato. Tieni presente che i proxy esistenti potrebbero non funzionare sui processori di messaggi appena aggiornati.
    • Una volta eseguito l'upgrade di tutti i processori di messaggi alla versione 4.53.01 di Edge per il cloud privato , esegui il deployment della revisione del proxy appena creata con l'espressione JSONPath corretta.
    • Riprendere il traffico su questi proxy.
  • Riprogettazione del proxy prima dell'upgrade

    Puoi riprogettare il proxy prima di eseguire l'upgrade a Edge per il cloud privato 4.53.01. Anziché fare affidamento su espressioni di percorso JSON specifiche, puoi ottenere lo stesso risultato utilizzando un metodo diverso.

    Ad esempio, se utilizzi una policy Estrai variabile con un percorso JSON, puoi sostituirla con una policy JavaScript che estrae dati simili prima di eseguire l'upgrade alla versione più recente. Al termine dell'upgrade, puoi ripristinare l'utilizzo dei percorsi JSON con i formati più recenti per il proxy.

Modifiche a JavaCallout

Contesto

Edge for Private Cloud 4.53.00 e versioni precedenti conteneva una directory denominata deprecated ($APIGEE_ROOT/edge-message-processor/lib/deprecated) che conteneva una serie di librerie JAR. Queste librerie erano disponibili per l'utilizzo nel codice Java nel criterio JavaCallout e potevano essere utilizzate direttamente o indirettamente dal tuo codice Java personalizzato.

Modifiche

La directory deprecata è stata rimossa in Edge per la versione 4.53.01 del cloud privato. Se il tuo codice Java si basa su queste librerie, i proxy che utilizzano questi callout Java non funzioneranno quando i processori di messaggi verranno aggiornati alla versione 4.53.01. Per evitare questi errori, segui i passaggi di mitigazione riportati di seguito prima di eseguire l'upgrade dei message processor alla versione 4.53.01.

Attenuazione

  1. Esamina i criteri Java-Callout e i file JAR associati e identifica se qualcuno di questi fa riferimento o utilizza librerie presenti nella directory "deprecated" dei tuoi attuali message processor. Tieni presente che i callout Java potrebbero utilizzare i file JAR caricati come risorse a livello di organizzazione o ambiente. Prendi in considerazione anche queste librerie.
  2. Una volta identificate le librerie obsolete , puoi seguire uno dei metodi riportati di seguito per risolvere il problema.
    • Posizionamento delle risorse (consigliato se hai un numero ridotto di file JAR / librerie della directory ritirata a cui fanno riferimento i file JAR Java-Callout)
      • Carica i file JAR ritirati identificati come risorsa al livello desiderato: revisione del proxy API, ambiente o organizzazione.
      • Procedi con l'upgrade del software Apigee come di consueto.
    • Posizionamento manuale (consigliato se hai un numero elevato di file JAR / librerie a cui fanno riferimento i file JAR Java-Callout)
      • Su ogni nodo del processore di messaggi, crea una nuova directory denominata external-lib nel percorso $APIGEE_ROOT/data/edge-message-processor/.
      • Copia i file JAR identificati nella directory external-lib dalla directory ritirata: cp $APIGEE_ROOT/edge-message-processor/lib/deprecated/some.jar $APIGEE_ROOT/data/edge-message-processor/external-lib/some.jar
      • Assicurati che la directory e i file JAR sottostanti siano leggibili dall'utente Apigee: chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • Procedi con l'upgrade del software Apigee come di consueto.

Modifica OpenLDAP

Contesto

OpenLDAP può essere utilizzato in Edge Private Cloud sia per l'autenticazione che per l'autorizzazione. In Edge for Private Cloud 4.53.01, il software OpenLDAP fornito da Apigee è stato aggiornato dalla versione 2.4 alla 2.6.

Modifiche

In OpenLDAP 2.6, il nome distinto relativo (RDN) è limitato a circa 241 byte/caratteri. Questo limite è un tetto massimo applicato e non può essere modificato.

Impatto
  • Si verificano errori di replica o importazione per le voci con RDN eccessivamente grandi.
  • Il tentativo di creare entità come organizzazioni,ambienti, ruoli personalizzati, autorizzazioni e così via potrebbe generare il messaggio di errore: "message": "[LDAP: error code 80 - Other]".
  • Sono interessati tutti i DN più lunghi di 241 byte nel LDAP di Apigee. Questi DN impediranno l'upgrade riuscito del software Apigee OpenLDAP e dovrai seguire le strategie di mitigazione per questi elementi prima di poter procedere con l'upgrade.

In genere, in LDAP di Apigee, i nomi distinti lunghi sono correlati alle autorizzazioni, in quanto vengono creati concatenando più entità. Queste voci di autorizzazione sono particolarmente soggette a problemi di upgrade.

Ad esempio, 

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

In genere, i nomi dell'organizzazione, dell'ambiente e del ruolo hanno una lunghezza tale che gli RDN in LDAP risultino inferiori a 241 byte.

Attenuazione

Prima dell'upgrade alla versione 4.53.01:

I passaggi seguenti ti aiuteranno a verificare la presenza di nomi distinti relativi lunghi nel cluster LDAP 2.4 esistente.

#1 - Estrai i dati LDAP

Utilizza il comando ldapsearch per trovare il nome distinto (dn) e reindirizzare l'output a un file: 

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

Assicurati che il file DN.ldif sopra contenga voci LDAP.

N. 2 - Identifica gli RDN lunghi

Individua gli RDN che superano i 241 byte/caratteri dal file DN.ldif sopra:

cat /tmp/DN.ldif |  grep '^dn:' | gawk -F',|dn: ' '{ rdn = $2; char_count = length(rdn); cmd = "echo -n \"" rdn "\" | wc -c"; cmd | getline byte_count; close(cmd); if (char_count > 241 || byte_count > 241) { print rdn, "(chars: " char_count ") (bytes: " byte_count ")"; }}'
o=VeryLongOrgNameWithMoreThan241Chars.... (chars: 245) (bytes: 245)
cn=VeryLongCustomRoleNameWithMoreThan241Chars.... (chars: 258) (bytes: 258)

Se il comando precedente non produce alcun output, significa che nessun RDN nella configurazione LDAP esistente supera i 241 byte/caratteri. Puoi procedere con l'upgrade come di consueto.

Se il comando precedente genera un output, indica la presenza di RDN che superano i 241 byte/caratteri. Per questi elementi, segui i passaggi di mitigazione descritti nel passaggio 3 prima di procedere con l'upgrade di Edge for Private Cloud 4.53.01.

N. 3: gestione di RDN lunghi

Se ricevi l'output dal passaggio 2, significa che sono presenti RDN che superano i 241 byte/caratteri. Segui i passaggi di mitigazione riportati di seguito:

Controlla le voci LDAP che superano i 241 byte.

  • Se il nome del ruolo personalizzato, dell'app, del prodotto API o di altre entità è il fattore principale che causa la lunghezza del nome distinto relativo, esegui la migrazione a un'entità alternativa con un nome più breve.
  • Se il nome dell'organizzazione o dell'ambiente è il principale responsabile del nome distinto relativo lungo, dovrai eseguire la migrazione a un'altra organizzazione o a un altro ambiente con un nome più breve.

Continua a ripetere i passaggi precedenti finché il tuo LDAP non ha RDN più lunghi di 241 byte. Una volta raggiunto questo stato, procedi con l'upgrade della versione del cloud privato come di consueto.

Modifiche al fornitore di crittografia

Contesto

Questa modifica è un riporto di Edge for Private Cloud 4.53.00. In Edge for Private Cloud 4.53.00, il fornitore di crittografia interno è stato aggiornato da Bouncy Castle (BC) a Bouncy Castle FIPS (BCFIPS) per abilitare il supporto FIPS.

Modifiche

Se le norme JavaCallout si basano sull'utilizzo del provider BC originale, soprattutto quando si utilizza la funzionalità di sicurezza rafforzata nel provider BCFIPS (ad esempio, l'utilizzo di una coppia di chiavi comune sia per la crittografia che per la firma), queste norme JavaCallout dovranno essere modernizzate. I criteri JavaCallout che tentano di caricare il provider di crittografia Bouncy Castle utilizzando il nome BC potrebbero non riuscire perché il provider predefinito è cambiato. Questi criteri che utilizzano il provider BC potrebbero non funzionare più. Le implementazioni personalizzate che si basano sul vecchio fornitore di BC non saranno più accessibili e dovranno essere riviste e implementate di nuovo.

Attenuazione

La soluzione alternativa consigliata è utilizzare il provider BCFIPS. Le implementazioni di JavaCallout personalizzate che si basavano sul vecchio provider dovranno essere esaminate e implementate nuovamente utilizzando il provider Bouncy Castle FIPS, a cui è possibile accedere utilizzando la stringa "BCFIPS".

Strumento di rilevamento automatico delle modifiche

È prevista a breve la release di uno strumento di rilevamento delle modifiche. Questo strumento sarà in grado di analizzare e identificare proxy API, flussi condivisi, risorse e RDN LDAP potenzialmente interessati dalle varie modifiche descritte in questo articolo. Questo strumento dovrebbe aiutarti a identificare varie entità soggette a errori durante o dopo l'upgrade a Edge per il cloud privato 4.53.01.