Recupero e gestione dei Purpose con govdesk-batch

Questa guida descrive il processo end-to-end per richiedere, recuperare e configurare i Purpose utilizzando govdesk-batch. L’obiettivo è permettere all’utente operativo di:

  • predisporre i prerequisiti (accessi e dati necessari);

  • generare e registrare correttamente le chiavi (pubblica/privata) su GovDesk;

  • configurare PDND e recuperare i parametri di integrazione;

  • completare la configurazione su GovDesk;

  • caricare le analisi del rischio;

  • configurare le Daily Call per ciascun use case;

  • gestire casistiche speciali (es. WAAS, ISEE) e gli errori più comuni.

Glossario rapido

  • Purpose: finalità/uso dichiarato associato ad un use case, necessaria per l’abilitazione e l’accesso ai servizi.

  • Use case: scenario applicativo specifico (servizio + contesto di utilizzo) da configurare.

  • Analisi del rischio: artefatto/documento richiesto per specifici servizi o use case, da caricare su GovDesk.

  • Daily call: limite/contatore operativo associato all’uso del servizio per singolo use case.

Prerequisiti

Prima di avviare la configurazione assicurarsi di disporre di:

  1. Accesso a GovDesk con permessi adeguati (gestione chiavi, configurazioni e batch).

  2. Accesso alla piattaforma PDND per la registrazione chiavi e il recupero parametri applicativi.

  3. Informazioni complete sugli use case, almeno:

    • lista degli use case da attivare;

    • associazione use case ↔ e-service / interoperabilità;

    • eventuali vincoli e requisiti specifici (es. WAAS/ISEE).

  4. Facoltativo ma consigliato: disponibilità delle analisi del rischio o delle indicazioni per reperirle.

Panoramica del flusso operativo

Il flusso standard è:

  1. Generazione chiavi su GovDesk (privata + pubblica) per e-service e interoperabilità.

  2. Comunicazione/inserimento della chiave pubblica su PDND.

  3. Recupero da PDND dei parametri:

    • client_id

    • client_kid

    per entrambi: e-service e interoperabilità.

  4. Inserimento dei parametri (client_id e client_kid) nella configurazione di GovDesk.

  5. Recupero e caricamento delle analisi del rischio su GovDesk.

  6. Configurazione delle Daily Call per ciascun use case:

    • quale analisi del rischio usare;

    • quale daily call associare.

  7. Gestione casistiche speciali (WAAS/ISEE) se applicabili.

  8. Validazioni finali ed esecuzione batch.

Generazione delle chiavi su GovDesk

Per ciascuna delle due componenti (e-service e interoperabilità) è necessario generare una coppia di chiavi:

  • chiave privata (da conservare su GovDesk e non condividere);

  • chiave pubblica (da comunicare/inserire su PDND).

Passi operativi

  1. Accedere a GovDesk.

  2. Navigare nella sezione Chiavi / Key Management (o sezione equivalente prevista dall’istanza).

  3. Selezionare la tipologia di chiave da generare:

    • e-service

    • interoperabilità

  4. Generare la coppia chiavi.

  5. Salvare/annotare:

    • identificativo chiave (se presente);

    • fingerprint (se disponibile);

    • data/ora generazione.

Output atteso

  • chiave privata disponibile in GovDesk (non esportata in chiaro);

  • chiave pubblica esportabile/copiaribile (formato tipico: PEM).

Comunicare la chiave pubblica alla PDND

Per ognuna delle due tipologie (e-service, interoperabilità):

  1. Accedere a PDND.

  2. Individuare la sezione di configurazione applicativa/integrazione relativa all’ente/applicazione.

  3. Inserire la chiave pubblica generata su GovDesk.

  4. Salvare la configurazione.

Attenzione

  • Non invertire le chiavi tra e-service e interoperabilità.

  • Verificare che non ci siano spazi/righe alterate durante il copia-incolla del PEM.

Configurazione su PDND: recupero parametri

Dopo l’inserimento della chiave pubblica, dalla PDND recuperare i seguenti parametri:

  • client_id

  • client_kid

Questi parametri devono essere recuperati e conservati separatamente per:

  • e-service

  • interoperabilità

Checklist

  • [ ] recuperato client_id per e-service

  • [ ] recuperato client_kid per e-service

  • [ ] recuperato client_id per interoperabilità

  • [ ] recuperato client_kid per interoperabilità

Configurazione su GovDesk

Inserire i parametri ricevuti dalla PDND nella configurazione di GovDesk.

Passi operativi

  1. Accedere a GovDesk.

  2. Aprire la sezione Configurazioni / PDND / Client (o equivalente).

  3. Inserire per e-service:

    • client_id

    • client_kid

  4. Inserire per interoperabilità:

    • client_id

    • client_kid

  5. Salvare e applicare la configurazione.

Validazioni consigliate

  • Coerenza tra client_kid e la chiave pubblica registrata.

  • Assenza di parametri scambiati tra e-service e interoperabilità.

Recupero e caricamento delle analisi del rischio

Alcuni servizi/use case richiedono l’associazione ad una analisi del rischio.

Passi operativi

  1. Recuperare le analisi del rischio relative ai servizi/use case da abilitare.

  2. Accedere a GovDesk → sezione Analisi del rischio / Risk Analysis (o equivalente).

  3. Caricare i file/artefatti richiesti.

  4. Verificare che ogni analisi risulti:

    • correttamente caricata;

    • selezionabile in fase di associazione al use case.

Configurazione delle Daily Call

Per ciascun use case occorre configurare:

  • quale analisi del rischio utilizzare;

  • quale daily call associare.

Approccio consigliato

  1. Costruire una matrice di configurazione (anche in foglio di lavoro) con almeno:

    • use case

    • tipologia (e-service / interoperabilità)

    • analisi del rischio

    • daily call

  2. Applicare la configurazione su GovDesk.

Esempio di matrice (modello)

Use case

Tipo

Analisi del rischio

Daily call

<UC_1>

e-service

<RA_1>

<DC_1>

<UC_2>

interoperabilità

<RA_2>

<DC_2>

Casi speciali (WAAS, ISEE)

Alcuni servizi richiedono passaggi aggiuntivi. In particolare:

  • WAAS

  • ISEE

Passaggio aggiuntivo obbligatorio

È necessario inviare una email a INPS per richiedere l’abilitazione dei servizi.

Checklist operativa

  • [ ] email inviata a INPS con richiesta abilitazione

  • [ ] conferma abilitazione ricevuta

  • [ ] configurazione PDND completata (chiavi + parametri)

  • [ ] configurazione GovDesk completata (client_id/client_kid)

  • [ ] analisi del rischio associata correttamente

  • [ ] daily call associata correttamente

Gestione errori

Di seguito le casistiche più comuni, come riconoscerle e come risolverle.

Errori di autenticazione / autorizzazione

Sintomi

  • chiamate rifiutate dalla piattaforma;

  • errori riconducibili a credenziali/identità applicativa non valida.

Cause tipiche

  • client_id errato o non coerente con l’applicazione configurata;

  • client_kid non corrispondente alla chiave pubblica registrata;

  • chiave pubblica incollata in modo incompleto/alterato;

  • scambio dei parametri tra e-service e interoperabilità.

Risoluzione

  1. Verificare su PDND che la chiave pubblica associata sia quella corretta.

  2. Verificare in GovDesk che client_id e client_kid corrispondano alla stessa configurazione.

  3. Se necessario, rigenerare le chiavi (solo se previsto dalla procedura) e riallineare PDND/GovDesk.

Errori di configurazione use case / daily call

Sintomi

  • use case non risulta attivo o non produce i Purpose attesi;

  • limiti di chiamata non corretti o rifiuti legati al conteggio.

Cause tipiche

  • daily call associata al use case sbagliato;

  • analisi del rischio mancante o associata in modo errato;

  • incoerenza tra tipo (e-service/interoperabilità) e configurazione applicata.

Risoluzione

  1. Controllare la matrice use case ↔ analisi del rischio ↔ daily call.

  2. Verificare che l’analisi del rischio sia effettivamente caricata e selezionabile.

  3. Correggere le associazioni e rieseguire il batch.

Errori per casistiche speciali (WAAS/ISEE)

Sintomi

  • configurazione corretta ma servizio non abilitato/risponde come non autorizzato.

Cause tipiche

  • abilitazione INPS non ancora attiva o non completata.

Risoluzione

  1. Verificare lo stato della richiesta inviata a INPS.

  2. Attendere conferma e rieseguire la procedura dopo abilitazione.

Attenzioni operative

  • Evitare la generazione duplicata dei Purpose: prima di lanciare creazioni/recuperi, verificare se esistono già Purpose attivi per lo stesso use case.

  • Verificare sempre la corretta configurazione delle chiavi prima di procedere (coerenza chiave pubblica ↔ client_kid).

  • Controllare la coerenza tra use case, analisi del rischio e daily call: è la causa più frequente di errori “silenziosi” (configurazione formalmente valida ma operativamente errata).

  • Tenere traccia delle configurazioni con un changelog (data, operatore, modifiche).

Esecuzione e verifica post-configurazione

  1. Eseguire govdesk-batch per il recupero/gestione Purpose secondo la procedura operativa prevista.

  2. Validare i risultati:

    • Purpose creati/recuperati come atteso;

    • nessuna duplicazione;

    • associazioni use case corrette;

    • assenza di errori nei log.

  3. In caso di errore, consultare la sezione Gestione errori e ripetere solo i passi necessari.