# 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 {% @mermaid/diagram content="sequenceDiagram autonumber participant User as User participant Opencity as Opencity participant Connector as PDND Connector participant PDND as Piattaforma PDND participant ANPR as Erogatore (ANPR) ``` %% Fase 0: L'utente si autentica sulla piattaforma User->>Opencity: Accede mediante sistema di identità digitale Opencity-->>User: Restituisce un cookie di autenticazione User->>Opencity: Chiama /api/session-auth Opencity-->>User: Restituisce un token JWT relativo alla sessione utente %% Fase 1: L'utente compila il form User->>Opencity: Accede a un modulo Note right of User: il modulo contiene il componente attivo configurato per accedere alla PDND %% Fase 2.1: Il Opencity prepara la richiesta GET User->>Connector: GET /anpr/stato-famiglia?fiscal_code=XYZ&config_id=ABC&format=famiglia Connector->>Opencity: Verifica token JWT di OpenCity %% Fase 2.2: Il connector genera le asserzioni e ottiene un voucher Note right of Connector: Genera audit assertion
Genera client assertion Connector->>PDND: Richiesta voucher con client_assertion PDND-->>Connector: Restituisce voucher (token di autorizzazione) %% Fase 2.3: Il connector prepara la chiamata all'erogatore Note right of Connector: Genera signature Connector->>ANPR: Richiesta e-service ANPR-->>Connector: Risposta con dati anagrafici %% Fase 2.4: Il connector processa e firma la risposta Note right of Connector: formattazione e firma dei dati %% Fase 2.5: Il Opencity precompila i campi Connector->>User: Visualizza dati ANPR %% Fase 3.1: L'utente conferma il form User->>Opencity: Invia form finale %% Fase 3.2: Il Opencity invia validazione Opencity->>Connector: POST /validate/anpr/stato-famiglia
fiscal_code=XYZ&config_id=ABC&format=famiglia
Body: {Data: ..., Meta: ...} Note right of Connector: validazione integrità dei dati alt Firma valida Connector-->>Opencity: 200 OK {"result": true} Opencity-->>User: Mostra conferma invio else Firma non valida Connector-->>Opencity: 200 OK {"result": false} Opencity-->>User: Mostra conferma invio ma senza i dati certificati dall'erogatore end %% Logging e compliance Note over Connector: Log per compliance:
- e_service_id (identificativo servizio ANPR)
- purpose_id (finalità accesso)
- client_id (identificativo client PDND)
- tax_code (codice fiscale utente)
- user_id (id utente SDC)
- tenant_id (id ente)" %} ``` ### Diagramma di interazione - Casi di errore {% @mermaid/diagram content="sequenceDiagram participant OC as User participant PC as PDND Connector participant PDND as Piattaforma PDND participant ANPR as Ente Erogatore (ANPR) ``` %% Flusso principale OC->>PC: 1. Richiesta dati ANPR (GET) Note over OC,PC: Config ID, Fiscal Code, Format %% Validazione token PC->>PC: 2. Validazione token JWT alt Token non valido PC-->>OC: 401 Unauthorized Note over PC,OC: "unauthenticated" end %% Caricamento configurazione PC->>PC: 3. Caricamento configurazione alt Config non trovata PC-->>OC: 404 Not Found Note over PC,OC: "config not found" end %% Generazione Audit Assertion PC->>PC: 4. Generazione Audit Assertion alt Errore generazione PC-->>OC: 500 Internal Error Note over PC,OC: "unable to parse private key" end %% Generazione Client Assertion PC->>PC: 5. Generazione Client Assertion alt Errore generazione PC-->>OC: 500 Internal Error Note over PC,OC: "file to sign audit assertion" end %% Richiesta Voucher PC->>PDND: 6. Richiesta Voucher alt Voucher non ottenuto PDND-->>PC: 401 Unauthorized PC-->>OC: 401 Unauthorized Note over PC,OC: "voucher not obtained" end %% Chiamata ANPR PC->>ANPR: 7. Richiesta dati Note over PC,ANPR: Voucher + Headers di sicurezza alt Codice fiscale non valido ANPR-->>PC: 400 Bad Request PC-->>OC: 400 Bad Request Note over PC,OC: "invalid fiscal code" else Codice fiscale non autorizzato ANPR-->>PC: 403 Forbidden PC-->>OC: 403 Forbidden Note over PC,OC: "permission denied: wrong fiscal code" else Dati non trovati ANPR-->>PC: 404 Not Found PC-->>OC: 404 Not Found Note over PC,OC: "data not found" else Errore interno ANPR ANPR-->>PC: 500 Internal Error PC-->>OC: 500 Internal Error Note over PC,OC: "internal error" end %% Risposta positiva alt Risposta OK ANPR-->>PC: 200 OK PC->>PC: 8. Formattazione dati PC->>PC: 9. Generazione firma PC-->>OC: 200 OK Note over PC,OC: Dati + Meta con firma end %% Flusso di validazione OC->>PC: 10. Richiesta validazione Note over OC,PC: Data + Signature alt Validazione OK PC-->>OC: 200 OK Note over PC,OC: {result: true} else Validazione fallita PC-->>OC: 200 OK Note over PC,OC: {result: false} else Errore validazione PC-->>OC: 500 Internal Error Note over PC,OC: "error verifying signature" end" %} ``` ### 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 ` * Header `Agid-JWT-TrackingEvidence: ` * Header `Digest: SHA-256=` * Header `Agid-JWT-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 7. **Risposta di Validazione**\ Il Connector risponde con un semplice booleano: 1. `true` se la firma è valida e i dati non sono stati alterati 2. `false` se la firma non è valida o i dati sono stati modificati Questo flusso di validazione è fondamentale perché: 1. Garantisce l'integrità dei dati tra il momento in cui vengono ottenuti dal Connector e il momento in cui vengono utilizzati da Opencity 2. Previene la manipolazione dei dati durante la trasmissione 3. Fornisce una prova verificabile dell'autenticità dei dati 4. 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 {% @mermaid/diagram content="sequenceDiagram participant OC as User participant PC as PDND Connector participant PDND as Piattaforma PDND participant ANPR as Erogatore (ANPR) ``` %% Fase di Fruizione rect rgb(200, 255, 200) Note over OC,ANPR: Fase di Fruizione OC->>PC: 1. Richiesta dati (GET) PC->>PDND: 2. Autenticazione PDND PDND-->>PC: 3. Voucher PC->>ANPR: 4. Richiesta dati ANPR-->>PC: 5. Dati PC->>PC: 6. Generazione firma Note over PC: Dati → JSON → SHA-256 → RSA (privata) → Base64 PC-->>OC: 7. Dati + meta.signature end %% Fase di Validazione rect rgb(255, 200, 200) Note over OC,PC: Fase di Validazione OC->>PC: 8. Richiesta validazione Note over OC,PC: Dati + meta.signature PC->>PC: 9. Verifica firma Note over PC: Dati → JSON → SHA-256 Note over PC: meta.signature → Base64 → RSA (pubblica) alt Firma valida PC-->>OC: 10. Risposta: true Note over PC,OC: Dati non alterati else Firma non valida PC-->>OC: 10. Risposta: false Note over PC,OC: Dati alterati end end" %} ``` 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.