Integrazione tecnica tra OpenCity, PDND Connector e PDND

Introduzione

Il pdnd-connector è un microservizio che funge da intermediario tra OpenCity e la piattaforma PDND, gestendo la complessità dell'autenticazione (ottenimento del voucher) e la comunicazione con gli enti erogatori di e-service (come ANPR e INPS). Espone delle API per OpenCity che consentono la fruizione e la validazione dei dati.

Diagramma di sequenza dell’integrazione

Glossario

Token JWT di Opencity

E' il token che collegato all'utenza del cittadino. Il contenuto è il seguente

• username (codice fiscale utente)

• roles (USER_ROLE)

• exp (data scadenza)

• tenant_id

Audit assertion

L'audit assertion è un token JWT che viene utilizzato per tracciare e verificare le operazioni effettuate sui servizi dell'ente erogatore (es. ANPR). Esso, oltre alle solite info contenute in un token JWT, è composto anche dalle seguenti informazioni di contesto:

• aud (audience): destinatario del token (il servizio dell'ente erogatore)

• purposeId: identificativo dello scopo della richiesta

• iss (issuer): identificativo del client che fa la richiesta

• sub (subject): identificativo del client

• userID: identificativo dell'utente che fa la richiesta

• userLocation: codice IPA dell'ente

• LoA (Level of Assurance): livello di autenticazione

L'audit assertion viene utilizzato in due modi principali:

1. Come header Agid-JWT-TrackingEvidence nelle richieste HTTP verso i servizi dell'ente erogatore

2. Come base per generare il client assertion (viene fatto l'hash SHA-256 dell'audit assertion)

Questo meccanismo serve a:

• Tracciare chi ha fatto la richiesta

• Verificare l'autenticità della richiesta

• Garantire la non ripudiabilità delle operazioni

• Mantenere un audit trail delle operazioni effettuate

Il token viene firmato usando una chiave privata RSA del client PDND per garantire l'autenticità e l'integrità dei dati.

Client assertion

Il client assertion è un token JWT che viene generato dopo l'audit assertion e serve in fase di richiesta dati dall'ente erogatore come prova di autenticazione del client verso il servizio di autenticazione PDND.

Signature

E' una firma digitale che viene utilizzata per garantire che i dati inviati dal cittadino all'invio del modulo non siano stati alterati rispetto a quando sono stati restituiti al cittadino dal pdnd-connector dopo averli richiesti al servizio dell'ente erogatore. La firma contiene:

• Digest SHA256 del payload

• Headers firmati (Content-Type, Digest)

Diagramma di interazione - Happy Path

Diagramma di interazione - Casi di errore

Descrizione Flusso di Fruizione

1. Autenticazione Iniziale Il flusso ha inizio quando un cittadino si autentica su Opencity attraverso il proprio sistema di identità digitale (SPID, CIE, ecc.). Questa autenticazione genera un JWT token che contiene:

   • Username (codice fiscale)

   • Tenant ID

   • Ruoli

   • Timestamp di scadenza

2. Avvio della Richiesta Quando il cittadino inizia a compilare un modulo che utilizza un Nested Form abilitato PDND, il PDND Connector riceve una richiesta che include tre elementi fondamentali:

   1. Config ID (identifica la configurazione del servizio)

   2. Codice fiscale

   3. Format (formato di output richiesto)

3. Configurazione del Connector Il PDND Connector, che funge da intermediario sicuro tra Opencity e la PDND, utilizza le configurazioni precedentemente salvate per preparare la richiesta. Queste configurazioni includono

   1. Client ID

   2. KID (Key ID)

   3. Chiave privata RSA

   4. Service Audience

   5. Purpose ID

   6. Endpoint del servizio

   Il Connector gestisce in modo sicuro sia le chiavi pubbliche che private, esponendo solo le chiavi pubbliche attraverso le API.

4. Autenticazione a Due Livelli Il Connector inizia un processo di autenticazione a due livelli con la PDND:

   1. Primo Livello (Audit Assertion): Un token JWT firmato con la chiave privata del client, contenente: iat, exp, nbf, aud, purposeId, iss, sub, jti, dnonce, userID, userLocation, LoA. Il token ha una validità di 60 minuti.

   2. Secondo Livello (Client Assertion): Un token JWT che include l'hash SHA-256 dell'Audit Assertion, esso contiene: iss, aud, jti, iat, nbf, exp, purposeId, sub, digest. Il token ha una validità di 24 ore.

5. Ottenimento del Voucher Il Client Assertion viene utilizzato per ottenere dalla PDND il Voucher di accesso al servizio. Il Voucher rappresenta l'autorizzazione effettiva ad accedere al servizio richiesto all'ente erogatore. Per motivi di compliance legale, il Voucher viene salvato localmente o su S3, creando un audit trail delle operazioni effettuate.

6. Chiamata al Servizio Erogatore Con il Voucher in mano, il PDND Connector contatta direttamente l'API dell'Ente Erogatore (come ANPR). La richiesta viene arricchita con diversi header di sicurezza:

   • Header Authorization: Bearer <voucher>

   • Header Agid-JWT-TrackingEvidence: <audit_assertion>

   • Header Digest: SHA-256=<digest64>

   • Header Agid-JWT-Signature: <signature>

   Il payload contiene i parametri della richiesta (es. codice fiscale)

7. Elaborazione della Risposta Quando l'Ente Erogatore risponde, il PDND Connector:

   1. Elabora la risposta per renderla compatibile con il formato atteso dal Nested Form

   2. Aggiunge una sezione "meta" che include una firma digitale dei dati ricevuti

   3. La firma viene generata usando SHA-256 per l'hashing dei dati e la chiave privata RSAper la firma

8. Verifica e Restituzione La risposta finale, che include sia i dati formattati che la sezione meta con la firma, viene restituita all'area personale. Il client può verificare la firma usando la chiave pubblica, garantendo che:

   1. I dati non siano stati modificati durante la trasmissione

   2. I dati provengano effettivamente dalla fonte dichiarata

Descrizione Flusso di Validazione

1. Ricezione dei Dati Il flusso di validazione inizia quando l'area personale (backend) riceve i dati e la firma digitale dalla chiamata GET al PDND Connector. Questi dati includono:

   1. Il campo data contenente le informazioni richieste (es. dati di residenza o stato famiglia)

   2. Il campo meta che contiene la firma digitale (signature) generata dal Connector

2. Preparazione della Richiesta di Validazione L'area personale prepara una richiesta di validazione che include:

   1. I dati da validare (data)

   2. La firma digitale (signature)

   3. Il Config ID che identifica la configurazione del servizio

   4. Il formato dei dati

   5. Il codice fiscale dell'utente

3. Invio al Connector La richiesta di validazione viene inviata al PDND Connector, che funge da validatore ufficiale dei dati. Questo passaggio è cruciale perché il Connector è l'unico componente che possiede le chiavi necessarie per verificare l'autenticità della firma.

4. Caricamento della Chiave Pubblica Il Connector:

   1. Carica la configurazione del servizio usando il Config ID

   2. Recupera il Client ID associato

   3. Carica la chiave pubblica RSA del client Questa chiave pubblica è essenziale per la verifica della firma, poiché è la controparte della chiave privata usata per firmare i dati.

5. Verifica della Firma Il Connector esegue la verifica della firma attraverso un processo in più fasi:

   1. Serializza i dati in formato JSON

   2. Calcola l'hash SHA-256 dei dati

   3. Verifica la firma usando la chiave pubblica RSA

   4. Confronta il risultato con la firma ricevuta

6. Gestione del Risultato Il Connector gestisce il risultato della verifica:

   1. Se la verifica ha successo, significa che i dati non sono stati alterati

   2. Se la verifica fallisce, significa che i dati potrebbero essere stati modificati

   In caso di errori durante il processo di verifica, viene restituito un errore specifico

Step 7: Risposta di Validazione Il Connector risponde con un semplice booleano:

• true se la firma è valida e i dati non sono stati alterati

• false se la firma non è valida o i dati sono stati modificati

Questo flusso di validazione è fondamentale perché:

• Garantisce l'integrità dei dati tra il momento in cui vengono ottenuti dal Connector e il momento in cui vengono utilizzati da Opencity

• Previene la manipolazione dei dati durante la trasmissione

• Fornisce una prova verificabile dell'autenticità dei dati

• Contribuisce alla creazione di un audit trail completo delle operazioni

Validazione dei Dati PDND

Contesto della Validazione

La validazione dei dati PDND avviene in un contesto specifico: quando un utente compila un form in OpenCity che include campi pre-compilati con dati provenienti dalla PDND (nested form con pdndField: true). Questi dati, essendo certificati dalla PDND, devono mantenere la loro integrità durante l'intero processo di compilazione del form.

Scopo della Validazione

La validazione serve a garantire che i dati certificati dalla PDND non siano stati alterati dopo essere stati forniti dal pdnd-connector. Questo è fondamentale perché:

• Mantiene l'affidabilità delle informazioni certificate

• Previene la manipolazione manuale dei dati da parte dell'utente

• Garantisce la tracciabilità e la non ripudiabilità delle informazioni

Hai ragione, ecco una versione più dettagliata del processo di validazione della firma digitale, con particolare attenzione al collegamento tra la firma generata in fase di fruizione e quella verificata in fase di validazione:

Processo di Validazione della Firma Digitale

Generazione della Firma (Fase di Fruizione)

Quando il pdnd-connector restituisce i dati in risposta a una richiesta GET, genera una firma digitale attraverso questi passaggi:

1. Preparazione dei Dati:

   • I dati vengono serializzati in JSON

   • L'ordine dei campi è importante per la consistenza della firma

2. Generazione della Firma:

   • Viene calcolato l'hash SHA-256 dei dati JSON

   • La firma viene generata usando la chiave privata RSA

   • La firma viene codificata in Base64

   • Meccanismo di Firma

     • Algoritmo di Hash: SHA-256

     • Algoritmo di Firma: RSA con padding PKCS1v15

     • Codifica: Base64

     • Posizione: Campo meta.signature nella risposta JSO

3. Inclusione nella risposta:

   • La firma viene inclusa nel campo meta.signature

   • Vengono aggiunti altri metadati per il contesto

Verifica della Firma (Fase di Validazione)

Quando arriva una richiesta di validazione, il pdnd-connector verifica che i dati non siano stati alterati:

1. Ricezione della Richiesta:

   • Riceve i dati da validare

   • Riceve la firma originale nel campo meta.signature

2. Preparazione per la Verifica:

   • I dati ricevuti vengono serializzati in JSON

   • È fondamentale che la serializzazione avvenga nello stesso modo della fase di fruizione

3. Verifica della Firma:

   • Viene decodificata la firma Base64

   • Viene calcolato l'hash SHA-256 dei dati ricevuti

   • La firma viene verificata usando la chiave pubblica RSA

4. Risposta di Validazione:

   • Se la verifica fallisce, restituisce false

   • Se la verifica ha successo, restituisce true

Collegamento tra Fruizione e Validazione

È cruciale comprendere che:

1. La firma verificata in fase di validazione deve essere esattamente la stessa generata in fase di fruizione

2. Qualsiasi modifica ai dati, anche minima, causerà il fallimento della validazione

3. Il processo di serializzazione JSON deve essere identico in entrambe le fasi

Esempio di Flusso Completo

Questo processo garantisce che:

• I dati non siano stati alterati durante la trasmissione

• La firma sia autentica e proveniente dal pdnd-connector

• L'integrità dei dati sia mantenuta durante l'intero ciclo di vita

Regole di Conservazione

Voucher PDND

• Durata: Conservazione obbligatoria per 24 mesi

• Scopo: Garantire la tracciabilità delle operazioni

• Base Legale: Requisito di compliance

Dati di Validazione

• I dati originali e le firme vengono conservati per:

  • Audit trail

  • Verifica post-facto

  • Compliance normativa

Aspetti di Sicurezza e Privacy

Analisi del Rischio

• L'ente fruitore deve dichiarare:

  • Finalità legali dell'accesso

  • Tipologia di dati personali

  • Basi giuridiche del trattamento

  • Misure di sicurezza adottate

Responsabilità

• L'ente è titolare del trattamento

• Deve fornire informative privacy appropriate

• Deve garantire la sicurezza dei dati

Questa struttura rende più chiara la separazione tra i vari aspetti della validazione, evidenziando il contesto, lo scopo, il processo e le regole di conservazione in modo distinto e logico.