GovWay v3.3.1

Nuova Gestione degli Errori generati da GovWay

Sono state completamente riviste le informazioni di errore ritornate al client, in seguito ad anomalie rilevate da GovWay nella gestione della richiesta o della risposta.

Oltre agli errori già previsti nelle interfacce dell'API, gli applicativi client possono ricevere due tipi di errori generati direttamente da GovWay:

• Errori Client: identificabili da un codice http 4xx su API REST o da un fault code 'Client' su API SOAP. Indicano che GovWay ha rilevato problemi nella richiesta effettuata dal client (es. errore autenticazione, autorizzazione, validazione contenuti...).

• Errori Server: identificabili dai codici http 502, 503 e 504 per le API REST o da un fault code 'Server' generato dal Gateway e restituito con codice http 500 per le API SOAP.

La codifica degli errori prodotta dal Gateway permette alle applicazioni client di discriminare tra errori causati da una richiesta errata, per i quali è quindi necessario intervenire sull'applicazione client prima di effettuare nuovi invii, ed errori dovuti allo stato dei servizi invocati, per i quali è invece possibile continuare ad effettuare la richiesta.

Per ciascun errore GovWay riporta le seguenti informazioni:

• Un codice http su API REST o un fault code su API SOAP.
• Un codice di errore, indicato nell'header http 'GovWay-Transaction-ErrorType', che riporta l'errore rilevato dal gateway (es. AuthenticationRequired, TokenExpired, InvalidRequestContent ...).
• Un identificativo di transazione, indicato nell'header http 'GovWay-Transaction-ID', che identifica la transazione in errore, utile principalmente per indagini diagnostiche.
• Un payload http, contenente maggiori dettagli sull'errore, opportunamente codificato per API REST (Problem Details - RFC 7807) o SOAP (Fault).

Nella configurazione di default di GovWay, gli errori restituiti ai client non contengono dettagli che possano causare disclosure di informazioni relative al dominio interno. In alcuni casi, per facilitare il supporto alla risoluzione di problemi, è comunque possibile abilitare la generazione di codici più specifici di errore ritornati al client nell'header http 'GovWay-Transaction-ErrorStatus'.

Nuova funzionalità di Tracciatura su File

La nuova funzionalità consente il tracciamento su file di tutte le informazioni relative alle comunicazioni gestite da GovWay.
Il successivo processamento del file da strumenti esterni (es. FileBeat) abilità così una facile integrazione con sistemi di tracciamento esterni (es. Logstash, Kafka, ...).

La funzionalità consente una completa personalizzazione delle informazioni da riportare su file di log, permettendo anche di definirne il formato e l'ordine in cui vengono salvate. È inoltre possibile suddividere le informazioni in più file di log in modo da facilitare l'invio di informazioni selezionate a destinazioni diverse.

Nuova funzionalità Gestione Proxy

Permette di gestire correttamente le situazioni in cui le comunicazioni tra GovWay e l'endpoint destinatario siano mediate dalla presenza di un proxy.

Nei casi più comuni si tratta di un "forward proxy". In questi casi l'indirizzo del proxy può essere censito sul connettore dell'Erogazione.

In scenari più complessi possono essere presenti reverse proxy che intervengono nella gestione delle connessioni https, utilizzando certificati client e/o trustStore differenti per diversi contesti applicativi.
In queste situazioni l'endpoint indicato nella configurazione del connettore su GovWay non è l'indirizzo remoto dell'applicativo ma bensì l'indirizzo del reverse proxy il quale a sua volta si occuperà di inoltrare la richiesta agli indirizzi a lui noti.

In questa situazione, è necessario configurare gli endpoint delle API sia su GovWay (indirizzo del reverse proxy), che sul reverse proxy (indirizzo dell'Erogatore finale)

Per semplificare la gestione di questo scenario architetturale, dalla versione 3.3.1 GovWay può passare l'indirizzo remoto dell'applicativo al proxy tramite un header HTTP o un parametro della url. In questo modo il censimento degli applicativi viene effettuato esclusivamente su GovWay.

Miglioramenti al Profilo di Interoperabilità ModI PA

È adesso possibile estendere il profilo di sicurezza messaggio IDAR03/IDAS03 in modo che il token di sicurezza ModI PA contenga:

• Digest Richiesta: nel token di sicurezza della risposta viene incluso il digest della richiesta. La funzionalità consente di implementare la soluzione per la non ripudiabilità della trasmissione come suggerito nelle linee guida di interoperabilità (punto D): https://docs.italia.it/italia/piano-triennale-ict/lg-modellointeroperabilita-docs/it/bozza/doc/doc_04/soluzioni-di-sicurezza.html#soluzioni-per-la-non-ripudiabilita-della-trasmissione.

• Informazioni Utente: le informazioni sull’utente che ha effettuato la richiesta.

Miglioramenti alle Console

Sono stati apportati i seguenti miglioramenti:

• Ricerca nelle liste a tendina: aggiunta la possibilità di selezionare incrementalmente nelle liste a tendina, tramite digitazione di caratteri.

• Highlight: aggiunto il supporto dell'highlight della keyword di ricerca effettuata sia all'interno delle liste che nei campi con funzionalità di 'autocomplete'.

Relativamente alla sola console di gestione:

• Risorse REST con qualsiasi path: aggiunta la possibilità di registrare manualmente risorse in API REST con HttpMethod definito e Path Qualsiasi.

• Modifica Risorsa: è stata aggiunta la possibilità di accedere al dettaglio di una risorsa, dall'elenco presente in una API, cliccando anche sul metodo http.

• Modifica Nome Applicativo: aggiunta la possibilità di modificare il nome di un applicativo precedentemente registrato.

• Modifica API di una Erogazione/Fruizione: aggiunta la possibilità di modificare l'API implementata in una erogazione o fruizione.

• Sospensione API: la sospensione di una API (erogazione/fruizione), o la successiva riattivazione, non necessita più un'operazione di reset delle cache. L'operazione effettuata tramite console è immediatamente attiva.

Relativamente alla sola console di monitoraggio

• Ricerca per ID Transazione: è adesso il primo criterio di ricerca per identificativo

• Pie Chart: nei report a torta, sulla destra di ogni voce presente nella legenda viene adesso riportato anche il numero di record oltra la %.

• Distribuzione Temporale: aggiunta la possibilità di personalizzare il numero di label da visualizzare sull'asse X nei report con distribuzione temporale.

• Nuovi esiti associati alle Transazioni:

  • 'Errore ModI PA': gli errori generati durante la validazione 'ModI PA' vengono adesso classificati con un esito dedicato;
  • 'Richiesta o Risposta già Elaborata': i nuovi esiti sono associati a transazioni riguadanti richieste o risposte duplicate.

• Escludi Richieste Scartate: il comportamento di default utilizzato nella sezione Transazioni e Statistiche può essere modificato tramite la proprietà 'transazioni.escludiRichiesteScartate.defaultValue' nel file di configurazione esterno '/etc/govway/monitor_local.properties'.

• Volume di Traffico Iniziale: il grafico che fornisce il volume di traffico complessivo, disponibile una volta collegati alla console, è adesso configurabile per restituire il volume complessivo di tutti i Profili di Interoperabilità abilitati sul gateway.

Miglioramenti alla funzionalità di Validazione dei Contenuti

• Nuovo Engine: la validazione dei contenuti, tramite interfaccia OpenAPI 3, utilizza adesso la libreria openapi4j (https://openapi4j.github.io/openapi4j/) che consente di validare correttamente messaggi definiti tramite strutture 'oneOf' con discriminator.

• Validazione solo per la Richiesta: la validazione è adesso "disattivabile" sulla fase di richiesta o risposta utilizzando le proprietà dell'API.

Miglioramenti alla funzionalità Importa e Esporta

Nella funzionalità 'Importa' della console è adesso possibile selezionare puntualmente se importare o meno nel registro di GovWay eventuali configurazioni o policy globali (Token, RateLimiting) presenti all'interno dell'archivio.

Anche per la funzionalità 'Esporta' è possibile indicare se includere nell'archivio esportato le policy globali riferite.

Miglioramenti alla funzionalità 'Header di Integrazione'

Aggiunte nuove modalità di interscambio delle informazioni che consentono di definire tramite un template "Freemarker" o "Velocity" come le informazioni di integrazione siano inserite nel messaggio inoltrato al backend (richiesta) o restituito al client (risposta).

Miglioramenti all'Installer

Aggiunto il supporto per la nuova versione dell'application server 'WildFly' 19.x

Bug Fix

Sono stati risolti i seguenti bug:

• Nella funzionalità di tracciamento con correlazione applicativa è adesso possibile definire regole multiple di correlazione anche per i messaggi JSON e non più solamente per messaggi XML. L'applicabilità di una regola è verificabile tramite l'utilizzo di un'espressione JSONPath.

• Le richieste 'OPTIONS', identificate tramite una risorsa definita nell'API con HttpMethod 'Qualsiasi', vengono adesso gestite come 'Request Preflight' se il CORS è abilitato nell'API.

• Gli header HTTP di integrazione specifici di un Profilo di Interoperabilità (es. Fatturazione Elettronica) non venivano gestiti correttamente in caso di attivazione dei 'metadati' di integrazione 'backward compatibility' il cui scopo è quello di produrre header di integrazione uguali a quelli generati da 'OpenSPCoop2' (es. x-openspcoop2-trasporto). Il problema è stato risolto e adesso tutti gli header generati sono stati allineati per essere retrocompatibili (es. X-SDI-*).

• L'accesso al database è stato ottimizzato per i seguenti casi:

  • Registrazione delle credenziali (trasporto, token) e dei tags/eventi nella transazione.
  • Funzionalità di arricchimento delle tracce, nel Profilo di Interoperabilità 'Fatturazione Elettronica'

• Sono stati disattivati i log generati dai template engine 'Freemarker' e 'Velocity' sul server log dell'Application Server.

• Aggiunta la possibilità di gestire gli header HTTP e i parametri delle URL all'interno di una trasformazione.

• L'identificativo del cluster numerico assegnabile alla proprietà 'org.openspcoop2.pdd.cluster_id.numeric' nel file 'govway_local.properties', veniva erroneamente gestito come intero invece che come stringa; questo comportava nel caso di numeri a due cifre che non si potessero utilizzare le prime 9 cifre definite come '0X' poichè si perdeva lo 0 iniziale. Il problema è stato corretto.

• Modificato il livello di severità da 'error' a 'info' del diagnostico che riporta l'esito di una comunicazione terminata con codice http 3xx di una API REST.

Per la console di gestione sono stati risolti i seguenti bug:

• Risolto problema, per quanto concerne il profilo 'ModI PA', che non consentiva di registrare gli applicativi autorizzati in presenza di Multi-Tenant abilitato.

• Corretto messaggio di warning presente durante la modifica di un referente di API (Profilo SPCoop); veniva erronamente visualizzato un id numerico al posto del nome del soggetto.

• La configurazione sui connettori multipli veniva erroneamente persa se venivano effettuate modifica nella sezione 'URL di Invocazione'.

• Corretto colore dei link visitati; veniva erroneamente utilizzato il colore associato all'hover.

• Se durante un aggiornamento veniva aggiunto un nuovo profilo di interoperabilità, senza che fosse stato creato sul database un soggetto di default associato, la console sollevava un errore generico. L'anomalia viene adesso segnalata correttamente.

Nelle funzionalità di 'importa' e 'esporta' sono stati risolti i seguenti bug.

• Aggiunti controlli di consistenza durante l'import di un archivio: vengono verificate la presenta di tutti gli elementi riferiti dalle configurazioni, compreso le Token Policy.

• Mediante il processo di importazione di una govlet era possibile creare un nuovo applicativo o soggetto con le stesse credenziali di uno già esistente.

• Revisione delle govlet per gestire correttamente il soggetto referente di 'default' per il Profilo API Gateway.

• Risolto problema presente durante l'esportazione di una API con Multi-Tenant abilitato e un soggetto selezionato in testata; l'archivio esportato era vuoto.

• L'esportazione di una erogazione, sulla quale era associato nel connettore un applicativo 'server', non veniva effettuata correttamente poichè tra gli elementi esportati non veniva inserito l'applicativo interno associato all'erogazione stessa.

• Importando un'archivio contenente una erogazione in cui era stato registrato nel controllo degli accessi un applicativo non esistente, l'operazione terminava con un errore inatteso. Aggiungendo l'applicativo mancante l'operazione terminava correttamente ma veniva generata una erogazione con stato disabilitato contenente erroneamente due gruppi (nell'erogazione originale esisteva solamente il gruppo predefinito). Entrambe le problematiche sono stati risolte.

• L'import di un archivio, contenente una una erogazione con connettore definito tramite Integration Manager, comportava una errata registrazione di un applicativo 'client'.

• Se su un connettore veniva prima abilitata la consegna su Integration Manager, definendo delle credenziali basic, e poi successivamente disabilitata, le credenziali rimanevano erroneamente assegnato all'applicativo. Il problema si evidenziava effettuando una esportazione ed una successiva importazione dell'erogazione. Terminato il processo di import veniva creato erroneamente un applicativo che possedeva il nome interno dell'erogazione e le credenziali che inizialmente erano state assegnate alla funzione I.M.

Sulla console di monitoraggio sono stati risolti i seguenti bug:

• Ritornando alla lista delle transazioni, dopo aver visionato il dettaglio di una transazione, viene adesso mantenuto chiuso il filtro di ricerca in modo da permettere una immediata consultazione di una transazione successiva presente nell'elenco.

• Risolto problema di visualizzazione dei contenuti di messaggi formato da solamente 2 caratteri (es. un semplice text/plain 'ok') che visualizzava erroneamente un messaggio vuoto.

• Il download dei contenuti applicativi utilizza adesso la corretta estensione del file, in relazione al Content-Type, anche per una registrazione avvenuto con la funzionalità di 'Dump Binario'. Prima del fix veniva utilizzata sempre l'estensione '.bin'.

• L'accesso al database è stato ottimizzato per alcune voci della console di monitoraggio che portano a pagine statiche e quindi non necessitano di query:

  • le voci del menù principale 'Transazioni' e 'Analisi Statistica'
  • le modalità di ricerca 'ID Transazione' e 'ID Messaggio'.

• Corretto colore dei link visitati; veniva erroneamente utilizzato il colore associato all'hover.

• L'export, di qualsiasi tipo, non conteneva le informazioni riguardanti il tipo di api (REST/SOAP) e i tags.

Per le API di configurazione e monitoraggio sono stati risolti i seguenti bug:

• Adeguate interfacce OpenAPI 3 per utilizzare un discriminator interno agli oggetti elencati nelle strutture oneOf, come richiesto dalla specifica OpenAPI "https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/". Nelle precedenti versioni il discriminator utilizzato era un claim esterno agli oggetti riferiti nella struttura oneOf.

• Aggiunta la possibilità, durante la creazione di una erogazione o fruizione, di ridefinire un nome o una versione differente da quella dell'API implementata.

• Ripristino log relativo all'http status code ritornato nel log govway_api[Config,Monitor]_transaction.log

• Aggiunti controlli di robustezza durante la creazione di una erogazione o fruizione di API SOAP, al fine di verificare la presenza obbligatoria del claim 'api_soap_servizio'.

• Corretta descrizione 'TAg' in govway_core.yaml.