Aggiornamento modalità di richiesta e utilizzo dei voucher [UPDATE] #1300
Description
A seguito del primo annuncio e delle comunicazioni inviate agli aderenti via mail e PEC, si offrono alcuni chiarimenti.
Scadenze
- 3 giugno 2025: adeguamento rilasciato negli ambienti di Collaudo e Attestazione;
- 1 luglio 2025: adeguamento rilasciato in ambiente di Produzione.
Cosa cambia per il fruitore?
Le richieste di voucher contenenti client assertion non conformi saranno rifiutate.
Il fruitore deve verificare che nella client assertion abbia inserito solamente claim ammessi, e che i valori dei claim siano del tipo corretto.
I claim ammessi sono i seguenti. Nell'header, kid, alg e typ. Nel payload, iss, sub, aud, jti, iat, exp e purposeId. Opzionalmente è possibile inserire il campo digest, con al suo interno due valori, alg e value.
I campi kid, alg, typ, iss, sub, aud, jti e purposeId devono essere stringhe. I campi iat ed exp sono long integer. Anche i campi digest.alg e digest.value sono stringhe.
Un esempio pratico di come è fatta una client assertion è disponibile qui.
FAQ fruitore
Il campo "nbf" è previsto dallo standard ma non lo vedo
Corretto, il campo "nbf" non è tra i claim ammessi e non va inserito nella client assertion.
Dove devo inserire i nuovi custom claim previsti? Intendo "producerId", "consumerId", "eserviceId", "descriptorId"
Non è il fruitore a doverli inserire. Sarà PDND Interoperabilità a restituirli automaticamente nel voucher che rilascia al fruitore.
Il campo "digest" è obbligatorio?
No, è opzionale e va inserito solamente se l'erogatore richiede di avere informazioni aggiuntive dal fruitore per uno specifico e-service.
Nella client assertion dovrei inserire anche i campi previsti dal "digest", come "userId", "userLocation", ecc. Come faccio?
Non vanno inseriti nella client assertion. Quei campi sono informazioni aggiuntive richieste da specifici erogatori per specifici e-service e fanno parte dell'interazione fra erogatore e fruitore, non devono essere noti a PDND Interoperabilità.
Per passarli all’erogatore, bisogna inserire quei campi nel secondo token previsto da AgID, l’“Integrity REST 02”. Questo secondo token sarà passato all’erogatore nell’header della chiamata verso la sua API, con chiave Agid-JWT-Tracking-Evidence.
Dal token creato per Integrity REST 02, calcolare l'hash usando l'algoritmo sha-256. A quel punto, inserire il valore risultante nel campo `digest` della client assertion, come
digest: {
alg: “SHA256”,
value: “IL_MIO_HASH”
}
Come faccio a sapere se la mia client assertion funziona?
Puoi usare lo strumento di debug presente nel back office alla voce Fruizione > Debug client assertion. Nell’ambiente di Collaudo, lo strumento è già stato adeguato per rispondere correttamente alla nuova configurazione.
Dove trovo maggiori informazioni?
Nel manuale tecnico. In particolare:
Inoltre, per un flusso completo, nel webinar dedicato.
Cosa cambia per l'erogatore?
Due cose:
- vengono inseriti quattro nuovi custom claim all'interno del voucher rilasciato da PDND Interoperabilità:
producerId,consumerId,eserviceId,descriptorId. I nuovi claim servono a semplificare le verifiche a carico dell’erogatore; - sono pubblicate le best practice per la verifica del voucher.
Le best practice emerse prevedono che l’erogatore possa fare una delle seguenti due verifiche:
- verificare l’audience (campo
aud) assieme alproducerId(l'id dell'erogatore). In questo modo, c'è la doppia certezza che la risorsa richiesta sia quella corretta, e che appartenga effettivamente al proprio ente; OPPURE - verificare la corrispondenza di
eserviceIdedescriptorId(id dell'e-service e della versione di e-service) rispetto alla propria risorsa. In questa maniera si ottiene una maggiore granularità di verifica.
FAQ erogatore
Sono obbligato ad adeguarmi se ho una configurazione particolare?
No, queste sono best practice che sono emerse e vengono caldamente consigliate, ma ogni erogatore può fare le proprie valutazioni in autonomia. È comunque responsabilità dell’erogatore garantire la robustezza delle proprie verifiche prima di restituire dati ai fruitori.
Quale delle due opzioni è la più sicura?
Non c’è una risposta univoca, dipende da come l’erogatore ha configurato l’infrastruttura e organizzato i propri servizi.
A cosa serve il quarto claim inserito, "consumerId"?
A facilitare ulteriori verifiche sul fruitore, qualora l’erogatore ne avesse necessità.
Devo fare altre verifiche?
Tutte quelle standard che sono previste in questi casi, come la verifica della firma (che il voucher sia firmato da PDND Interoperabilità), che il voucher sia in corso di validità, ecc.
Dove trovo maggiori informazioni?
Nel manuale tecnico. In particolare:
Inoltre, per un flusso completo, nel webinar dedicato.