[Documentazione]

Aggiunta descrizione dei profili non bloccanti per il Profilo di Interoperabilità "ModI PA".

ChangeLog

@@ -1,4 +1,4 @@
-2019-09-09  Andrea Poli <[email protected]>
+2019-09-10  Andrea Poli <[email protected]>
 
 	* Rilasciata versione 3.2.0.b1
 
@@ -17,6 +17,8 @@
 	Aggiunta funzionalità OP-841
 	Realizzato un nuovo profilo di interoperabilità 'ModI PA' che soddisfa le linee guida pubblicate al link:
 	- https://docs.italia.it/italia/piano-triennale-ict/lg-modellointeroperabilita-docs/it/bozza/
+	Il profilo "ModI PA" consente in maniera del tutto trasparente alle applicazioni interne al dominio, 
+	la conformità delle API (sia in fruzione che in erogazione) alle nuove Linee Guida AGID di Interoperabilità.
 	Il lavoro include diverse migliorie quali:	
 	- Aggiunta una cache dedicata a tutti i kestore acceduti dalle verie funzionalità del gateway come ssl, wssecurity, jws, jwe, oauth2 ...
 	- Al connettore https è stata aggiunta la possibilità di indicare opzionalmente l'alias della chiave privata da utilizzare per l'autenticazione client,

README.md

@@ -35,7 +35,7 @@ Il progetto [govway-docker](https://github.com/link-it/govway-docker) fornisce t
 ## Standard di Mercato
 Supporto API conformi ai protocolli standard di mercato, come SOAP 1.1 e 1.2, API restful serializzate in Json o XML o semplici dati binari su Http. L'integrazione avviene sempre tramite le API applicative native, indipendentemente dai profili di interoperabilità adottati, gestiti in maniera trasparente dal gateway.
 ## Conformità alle specifiche di interoperabilità italiane ed europee
-Supporto delle nuove linee guida per l'interoperabilità di AGID (MI 2018) e del "building block" eDelivery del progetto europeo CEF (Connecting European Facilities). Viene inoltre assicurata la retrocompatibilità con il protocollo SPCoop, ancora ampiamente adottato per i servizi della PA.
+Supporto delle nuove linee guida per l'interoperabilità di AGID (ModI PA) e del "building block" eDelivery del progetto europeo CEF (Connecting European Facilities). Viene inoltre assicurata la retrocompatibilità con il protocollo SPCoop, ancora ampiamente adottato per i servizi della PA.
 ## Registro delle API
 La registrazione delle API può avvenire manualmente o tramite caricamento dei descrittori delle interfacce (OpenAPI 3.0, Swagger e WADL per i servizi REST, WSDL per i servizi SOAP, Accordi di Servizio per i servizi SPCoop).
 ## Gestione Govlet

resources/doc/src/manuali/console/profiloModIPA/concettiPreliminari.rst

@@ -35,4 +35,6 @@ Nel processo di configurazione, tramite la govwayConsole, sono inoltre tenuti in
     + *[IDAS02 o IDAR02]  Direct  Trust  con  certificato  X.509  su  SOAP o REST  con  unicità  del token/messaggio*: estensione del profilo precedente con l'aggiunta di un meccanismo di filtro che impedisce il processamento di un messaggio di richiesta duplicato.
     + *[IDAS03 o IDAR03] Integrità del payload del messaggio SOAP o REST*: profilo che estende i profili precedenti aggiungendo la gestione della firma del payload come verifica di integrità del messaggio ricevuto.
 
+- *URL di Invocazione API*: le linee guida richiedono una indicazione esplicita della tecnologia utilizzata (REST o SOAP) e la versione. Le url con cui vengono esposte le API su GovWay soddisfano entrambi i requisiti.
+
 Tutti questi concetti sono stati recepiti e gestiti nelle maschere di configurazione della govwayConsole, adottando il profilo ModI PA. Le sezioni seguenti illustrano in dettaglio gli elementi di configurazione integrativi rispetto al profilo API Gateway.

resources/doc/src/manuali/console/profiloModIPA/index.rst

@@ -4,7 +4,12 @@
 Profilo 'ModI PA'
 ======================
 
-Il profilo ModI PA consente di produrre le configurazioni dei servizi in conformità a quanto previsto dalla normativa tecnica presente nel documento *Linee Guida Modello Interoperabilità* (https://docs.italia.it/italia/piano-triennale-ict/lg-modellointeroperabilita-docs/it/bozza/) rilasciato da AGID nel 2018.
+Il profilo 'ModI PA' consente in maniera del tutto trasparente alle
+applicazioni interne al dominio, la conformità delle API (sia in
+fruzione che in erogazione) alle nuove *Linee Guida AGID di
+Interoperabilità*
+(https://docs.italia.it/italia/piano-triennale-ict/lg-modellointeroperabilita-docs/it/bozza/).
+
 La struttura complessiva del processo di configurazione si mantiene analoga a quanto già descritto per il profilo API Gateway. Le differenze, con rispetto al profilo API Gateway, presentate in questa sezione, riguardano vincoli sulle scelte operabili dalla console e le informazioni di configurazione aggiuntive specifiche per la realizzazione degli scenari in accordo al Modello di Interoperabilità.
 
 .. toctree::

resources/doc/src/manuali/console/profiloModIPA/interazione/pullREST.rst

@@ -0,0 +1,110 @@
+.. _modipa_pullREST:
+
+Profilo di Interazione PULL per API REST
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Il profilo di interazione, denominato PULL, prevede che il fruitore non fornisca un indirizzo di callback, mentre l’erogatore fornisce un indirizzo interrogabile per verificare lo stato di processamento di una richiesta e, al fine dell’elaborazione della stessa, il risultato (:numref:`modipa_flusso_PULL_REST`).
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_REST.png
+    :scale: 50%
+    :align: center
+    :name: modipa_flusso_PULL_REST
+
+    Flusso previsto in un Profilo di Interazione PULL per API REST
+
+Come riportato dalle Linee Guida di Interoperabilità ModI PA:
+
+- L’interfaccia di servizio dell’erogatore fornisce tre metodi differenti al fine di inoltrare una richiesta, controllarne lo stato ed ottenerne il risultato
+- Al passo (1), il fruitore DEVE utilizzare il verbo HTTP POST;
+- Al passo (2), l’erogatore DEVE fornire insieme all’acknowledgement della richiesta, un percorso di risorsa per interrogare lo stato di processamento utilizzando HTTP header Location ; Il codice HTTP di stato DEVE essere HTTP status 202 Accepted a meno che non si verifichino errori;
+- Al passo (3), il fruitore DEVE utilizzare il percorso di cui al passo (2) per richiedere lo stato della risorsa; Il verbo HTTP utilizzato deve essere GET;
+- Al passo (4) l’erogatore indica che la risorsa non è ancora pronta, fornendo informazioni circa lo stato della lavorazione della richiesta; il codice HTTP restituito è HTTP status 200 OK;
+- Al passo (6) l’erogatore indica che la risorsa è pronta, utilizzando HTTP header Location ; per indicare il percorso dove recuperare la risorsa, il codice HTTP restituito è HTTP status 303 See Other;
+- Al passo (8) l’erogatore risponde con la rappresentazione della risorsa,Il codice HTTP restituito è HTTP status 200 OK;
+
+
+**Configurazione delle API**
+
+Per attuare la configurazione su GovWay si deve procedere con la registrazione dell'API che deve contenere le tre risorse differenti descritti precedentemente.
+
+- Richiesta
+
+Effettuata la registrazione delle API, accedere al dettaglio della risorsa corrispondente alla richiesta ed impostare nella sezione 'ModI PA' un profilo di interazione non bloccante 'PULL' con ruolo 'Richiesta' come mostrato nella figura :numref:`modipa_flusso_PULL_richiesta_REST`:
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_richiesta_REST.png
+    :scale: 40%
+    :align: center
+    :name: modipa_flusso_PULL_richiesta_REST
+
+    Configurazione della richiesta dell'API REST (PULL)
+
+- Richiesta Stato
+
+Successivamente, accedere al dettaglio dell'azione che consente di richiedere lo stato di processamento ed impostare nella sezione 'ModI PA' un profilo di interazione non bloccante 'PULL' con ruolo 'Richiesta Stato'. Definire anche la correlazione verso la risorsa relativa alla richiesta come mostrato nella figura :numref:`modipa_flusso_PULL_richiestaStato_REST`:
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_richiestaStato_REST.png
+    :scale: 40%
+    :align: center
+    :name: modipa_flusso_PULL_richiestaStato_REST
+
+    Configurazione della richiesta stato di processamento dell'API REST (PULL)
+
+- Risposta
+
+Accedere al dettaglio dell'azione corrispondente alla risposta ed impostare nella sezione 'ModI PA' un profilo di interazione non bloccante 'PULL' con ruolo 'Risposta'. Definire anche la correlazione verso la risorsa relativa alla richiesta come mostrato nella figura :numref:`modipa_flusso_PULL_risposta_REST`:
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_risposta_REST.png
+    :scale: 40%
+    :align: center
+    :name: modipa_flusso_PULL_risposta_REST
+
+    Configurazione della risposta dell'API REST (PUSH)
+
+**Configurazione dell'Erogazione**
+
+Sul dominio dell'erogatore deve essere definita l'erogazione dell'API.
+
+- Richiesta
+
+Le richieste ricevute sull'erogazione vengono inoltrate al backend da GovWay rimanendo poi in attesa dell'acknowledgement.
+
+Ricevuto il messaggio di acknowledgement GovWay verifica che il codice HTTP di stato sia 202 e verifica la presenza dell’header HTTP 'Location'. 
+
+
+- Richiesta Stato di Processamento
+
+Le richieste che richiedono uno stato del processamento vengono validate da GovWay verificando che il codice HTTP di stato sia 200 (risposta non ancora pronta) o 303 (risposta pronta ad essere recuperata). Nel caso il codice HTTP sia 303 viene anche verificata la presenza dell’header HTTP 'Location'.
+
+
+- Risposta
+
+Le risposte vengono gestite da GovWay vengono validate da GovWay verificando che il codice HTTP di stato sia 200.
+
+
+.. note::
+
+	**Id Correlazione**
+
+	GovWay estrae dal valore presente nell'header 'Location' (per la richiesta e la richiesta stato) e dall'endpoint (per la risposta) l'identificativo di correlazione al fine di correlare la richiesta con le successive operazioni.
+
+
+**Configurazione della Fruizione**
+
+Sul dominio del fruitore deve essere definita una fruizione dell'API.
+
+- Richiesta
+
+Le richieste devono essere inoltrate dall'applicativo mittente utilizzando la fruizione dell'API configurata su GovWay. 
+
+Il messaggio di acknowledgement ricevuto viene validato al fine di verificare la presenza dell'header http 'Location' come previsto dalla specifica 'ModI PA'. L'informazione sull'id di correlazione è ottenibile dall'applicativo mittente sulla risposta tramite gli header di integrazione descritti nella sezione :ref:`headerIntegrazione_richiestaInoltrata` e :ref:`headerIntegrazione_other` (per default tramite l'header http 'GovWay-Conversation-ID').
+
+- Richiesta Stato di Processamento e Risposta
+
+Le successive operazioni devono essere inoltrate dall'applicativo mittente utilizzando la fruizione dell'API configurata su GovWay. 
+
+
+.. note::
+
+	**Id Correlazione**
+
+	GovWay estrae dal valore presente nell'header 'Location' (per la richiesta) e dall'endpoint (per la richiesta stato e per la risposta) l'identificativo di correlazione al fine di correlare la richiesta con le successive operazioni.

resources/doc/src/manuali/console/profiloModIPA/interazione/pullSOAP.rst

@@ -0,0 +1,122 @@
+.. _modipa_pullSOAP:
+
+Profilo di Interazione PULL per API SOAP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Il profilo di interazione, denominato PULL, prevede che il fruitore non fornisca un indirizzo di callback, mentre l’erogatore fornisce un indirizzo interrogabile per verificare lo stato di processamento di una richiesta e, al fine dell’elaborazione della stessa, il risultato (:numref:`modipa_flusso_PULL_SOAP`).
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_SOAP.png
+    :scale: 50%
+    :align: center
+    :name: modipa_flusso_PULL_SOAP
+
+    Flusso previsto in un Profilo di Interazione PULL per API SOAP
+
+Come riportato dalle Linee Guida di Interoperabilità ModI PA:
+
+- L’interfaccia di servizio dell’erogatore fornisce tre metodi differenti al fine di inoltrare una richiesta, controllarne lo stato ed ottenerne il risultato
+- Al passo (1), il fruitore effettua una richiesta;
+- Al passo (2), l’erogatore DEVE fornire insieme all’acknowledgement della richiesta nel body, un correlation ID riportato nel header custom SOAP X-Correlation-ID;
+- Al passo (3), il fruitore DEVE utilizzare i l correlation ID ottenuto al passo (2) per richiedere lo stato di processamento di una specifica richiesta;
+- Al passo (4) l’erogatore, quando il processamento non si è ancora concluso fornisce informazioni circa lo stato della lavorazione della richiesta, quando invece il processamento si è concluso risponde indicando in maniera esplicita il completamento;
+- Al passo (5), il fruitore utilizza il correlation ID di cui al passo (2) al fine di richiedere il risultato della richiesta;
+- Al passo (6), l’erogatore fornisce il risultato del processamento.
+
+
+**Configurazione delle API**
+
+Per attuare la configurazione su GovWay si deve procedere con la registrazione dell'API che deve contenere i tre metodi differenti descritti precedentemente.
+
+- Richiesta
+
+Effettuata la registrazione delle API, accedere al dettaglio dell'azione corrispondente alla richiesta ed impostare nella sezione 'ModI PA' un profilo di interazione non bloccante 'PULL' con ruolo 'Richiesta' come mostrato nella figura :numref:`modipa_flusso_PULL_richiesta_SOAP`:
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_richiesta_SOAP.png
+    :scale: 40%
+    :align: center
+    :name: modipa_flusso_PULL_richiesta_SOAP
+
+    Configurazione della richiesta dell'API SOAP (PULL)
+
+- Richiesta Stato
+
+Successivamente, accedere al dettaglio dell'azione che consente di richiedere lo stato di processamento ed impostare nella sezione 'ModI PA' un profilo di interazione non bloccante 'PULL' con ruolo 'Richiesta Stato'. Definire anche la correlazione verso l'azione relativa alla richiesta come mostrato nella figura :numref:`modipa_flusso_PULL_richiestaStato_SOAP`:
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_richiestaStato_SOAP.png
+    :scale: 40%
+    :align: center
+    :name: modipa_flusso_PULL_richiestaStato_SOAP
+
+    Configurazione della richiesta stato di processamento dell'API SOAP (PULL)
+
+- Risposta
+
+Accedere al dettaglio dell'azione corrispondente alla risposta ed impostare nella sezione 'ModI PA' un profilo di interazione non bloccante 'PULL' con ruolo 'Risposta'. Definire anche la correlazione verso l'azione relativa alla richiesta come mostrato nella figura :numref:`modipa_flusso_PULL_risposta_SOAP`:
+
+   .. figure:: ../../_figure_console/modipa_flusso_PULL_risposta_SOAP.png
+    :scale: 40%
+    :align: center
+    :name: modipa_flusso_PULL_risposta_SOAP
+
+    Configurazione della risposta dell'API SOAP (PUSH)
+
+**Configurazione dell'Erogazione**
+
+Sul dominio dell'erogatore deve essere definita l'erogazione dell'API.
+
+- Richiesta
+
+Le richieste ricevute sull'erogazione vengono inoltrate al backend da GovWay rimanendo poi in attesa dell'acknowledgement.
+
+Ricevuto il messaggio di acknowledgement GovWay verifica la presenza dell’header SOAP custom 'X-Correlation-ID'. Se tale header non risulta presente viene generato da GovWay impostando come valore l'identificativo della transazione, che è stato inoltrato con la richiesta al backend tramite gli header di integrazione descritti nella sezione :ref:`headerIntegrazione_richiestaInoltrata` e :ref:`headerIntegrazione_other` (per default tramite l'header http 'GovWay-Transaction-ID').
+
+.. note::
+
+	**Header 'X-Correlation-ID' generato da GovWay**
+
+	La generazione dell'header soap 'X-Correlation-ID', se non presente, è disabilitabile intervenendo sulla proprietà "org.openspcoop2.protocol.modipa.soap.pull.request.correlationId.header.useTransactionIdIfNotExists" presente nel file “/etc/govway/modipa_local.properties” (si assume che '/etc/govway' sia la directory di configurazione indicata in fase di installazione). Se si disabilita la proprietà, GovWay termina con errore la transazione se rileva l'assenza dell'header soap 'X-Correlation-ID' nel messaggio di acknowledgement ricevuto dal backend.
+
+- Richiesta Stato di Processamento
+
+Le richieste che richiedono uno stato del processamento vengono validate da GovWay verificando la presenza dell'header soap 'X-Correlation-ID' come previsto dal profilo 'ModI PA'. Effettuata la validazione del messaggio di richiesta, eventualmente gestendo anche gli aspetti di sicurezza descritti nella sezione :ref:`modipa_sicurezzaMessaggio`, GovWay inoltra il messaggio al backend e rimane in attesa dell'acknowledgement. L'informazione sull'id di correlazione è inoltrato al backend, oltre che tramite l'header soap 'X-Correlation-ID', anche tramite gli header di integrazione descritti nella sezione :ref:`headerIntegrazione_richiestaInoltrata` e :ref:`headerIntegrazione_other` (per default tramite l'header http 'GovWay-Conversation-ID').
+
+- Risposta
+
+Le risposte vengono gestite da GovWay in maniera simile a quanto indicato per le richieste di stato del processamento.
+
+
+**Configurazione della Fruizione**
+
+Sul dominio del fruitore deve essere definita una fruizione dell'API.
+
+- Richiesta
+
+Le richieste devono essere inoltrate dall'applicativo mittente utilizzando la fruizione dell'API configurata su GovWay. 
+
+Il messaggio di acknowledgement ricevuto viene validato al fine di verificare la presenza dell'header soap 'X-Correlation-ID' come previsto dalla specifica 'ModI PA'. L'informazione sull'id di correlazione è ottenibile dall'applicativo mittente sulla risposta, oltre che tramite l'header soap 'X-Correlation-ID', anche tramite gli header di integrazione descritti nella sezione :ref:`headerIntegrazione_richiestaInoltrata` e :ref:`headerIntegrazione_other` (per default tramite l'header http 'GovWay-Conversation-ID').
+
+- Richiesta Stato di Processamento
+
+Le richieste che richiedono uno stato del processamento devono essere inoltrate dall'applicativo mittente utilizzando la fruizione dell'API configurata su GovWay. Le richieste vengono validate da GovWay verificando la presenza dell'header soap 'X-Correlation-ID'. GovWay permette di fornire l'informazione sull'identificativo di correlazione anche tramite modalità alternative all'header soap per poi generarlo come previsto dalla specifica 'ModI PA' valorizzato con il valore fornito. Le modalità alternative sono le seguenti:
+
+    - Header HTTP 'X-Correlation-ID'
+    - Header HTTP 'GovWay-Conversation-ID' o parametro della url 'govway_conversation_id' previsto per la correlazione tramite identificativo di collaborazione descritta nella sezione :ref:`correlazioneTransazioniDifferenti`. Questa modalità richiede che sia abilitata l'indicazione dell'identificativo di collaborazione nell'API o sulla singola azione come mostrato nella figura :numref:`abilitazioneIdCollaborazioneSOAP2`:
+
+        .. figure:: ../../_figure_console/abilitazioneIdCollaborazione_SOAP.png
+         :scale: 30%
+         :align: center
+         :name: abilitazioneIdCollaborazioneSOAP2
+
+         Abilitazione funzionalità di correlazione govway tramite identificativo di colllaborazione
+    - Header HTTP 'GovWay-Relates-To' o parametro della url 'govway_relates_to' previsto per la correlazione tramite riferimento della richiesta descritta nella sezione :ref:`correlazioneTransazioniDifferenti`. Questa modalità richiede che sia abilitata l'indicazione dell'identificativo di riferimento alla richiesta nell'API o sulla singola azione come mostrato nella figura :numref:`abilitazioneIdRiferimentoRichiestaSOAP2`:
+
+        .. figure:: ../../_figure_console/abilitazioneIdRiferimentoRichiesta_SOAP.png
+         :scale: 30%
+         :align: center
+         :name: abilitazioneIdRiferimentoRichiestaSOAP2
+
+         Abilitazione funzionalità di correlazione govway tramite identificativo della richiesta
+
+- Risposta
+
+Le risposte vengono gestite da GovWay in maniera simile a quanto indicato per le richieste di stato del processamento.