Tabella dei contenuti
Come verificare la validità di un voucher Bearer
L'erogatore di un e-service deve poter verificare la legittimità di qualsiasi richiesta ricevuta. Di seguito sono riportate le verifiche che PDND Interoperabilità suggerisce di fare per i voucher Bearer. È sempre facoltà dell'erogatore di valutare quali verifiche implementare, o implementarne altre aggiuntive, in base alla propria architettura applicativa.
Prima di tutto, l'erogatore estrae dall'header della richiesta del fruitore il voucher rilasciato da PDND Interoperabilità, e lo deserializza.
Esempio di voucher Bearer rilasciato da PDND Interoperabilità deserializzato
Header:
1{
2 "typ": "at+jwt",
3 "alg": "RS256",
4 "kid": "{KID_CHIAVE_PDND}"
5}
6Payload:
1{
2 "iss": "interop.pagopa.it",
3 "nbf": 1747408537,
4 "iat": 1747408537,
5 "exp": 1747409537,
6 "jti": "12297ac1-c192-4573-8350-207a4213e5ac",
7 "aud": "https://eservice.pa.it/api/v1",
8 "sub": "9b361d49-33f4-4f1e-a88b-4e12661f2309",
9 "client_id": "9b361d49-33f4-4f1e-a88b-4e12661f2309",
10 "purposeId": "1b361d49-33f4-4f1e-a88b-4e12661f2300",
11 "producerId" : "0e9e2dab-2e93-4f24-ba59-38d9f11198ca",
12 "consumerId" : "69e2865e-65ab-4e48-a638-2037a9ee2ee7",
13 "eserviceId" : "b8c6d7ad-93fc-4eaf-9018-3cd8bf98163f",
14 "descriptorId": "9525a54b-9157-4b46-8976-ec66f20b7d7e"
15}
16Significato dei campi
Nell'header si troveranno tre campi:
| Nome campo | Significato |
|---|---|
| kid | l'id della chiave che usato per firmare il voucher, reperibile sul well known di PDND Interoperabilità (vedi sotto Verifica sulla firma) |
| alg | l'algoritmo usato per firmare il JWT ( RS256) |
| typ | il tipo di oggetto che si sta inviando (at+jwt) |
Nel payload ci saranno invece tredici campi obbligatori, e uno opzionale:
| Nome campo | Significato |
|---|---|
| iss | l'issuer, rappresenta il dominio corrispondente all'authorization server di PDND Interoperabilità che ha rilasciato il voucher (ad esempio, l'issuer dell'ambiente di produzione è interop.pagopa.it) |
| nbf | not before, il timestamp dal quale è valido il voucher, espresso in UNIX epoch (valore numerico, non stringa). Per i voucher di PDND Interoperabilità, l'nbf corrisponde allo iat, ossia il voucher è spendibile immediatamente |
| iat | issued at, il timestamp nel quale è stato rilasciato il voucher, espresso in UNIX epoch (valore numerico, non stringa) |
| exp | l'expiration, il timestamp riportante data e ora di scadenza del token, espresso in UNIX epoch (valore numerico, non stringa). La durata del voucher (ossia la differenza tra nbf ed exp) dipende dal valore che l'erogatore ha impostato nella configurazione dell'e-service |
| jti | il JWT ID, un id unico random assegnato da PDND Interoperabilità |
| aud | l'audience, ossia l'indicazione di quale servizio dell'erogatore il fruitore intenda consumare con il voucher. Il valore riportato è quello che l'erogatore ha inserito nella configurazione dell'e-service |
| sub | il subject, in questo caso l'id del client che ha richiesto il voucher a PDND Interoperabilità |
| client_id | l'identificativo unico del client del fruitore che ha richiesto il voucher a PDND Interoperabilità (corrisponde al sub) |
| purposeId | l'identificativo unico della finalità per la quale è rilasciato il voucher |
| producerId | l'identificativo unico dell'erogatore dell'e-service |
| consumerId | l'identificativo unico del fruitore |
| eserviceId | l'identificativo unico dell'e-service |
| descriptorId | l'identificativo unico della versione di e-service |
NB: il client_id è presente nel token e utilizza lo snake case invece del camel case per coerenza con l'RFC di riferimento.
Verifiche di base
Verifiche sugli header
Il voucher deve essere di tipo at+jwt.
Verifica sulla firma
L'erogatore scarica la lista di chiavi in uso da un file esposto nella cartella .well-known di PDND Interoperabilità. L'URL corretta è disponibile sull'interfaccia nel back office all'interno della scheda di ogni singolo e-service e varia in funzione dell'ambiente nel quale è stata fatta la richiesta (collaudo, attestazione, produzione).
A titolo di esempio, https://interop.pagopa.it/.well-known/jwks.json è quella di produzione.
All'interno del file, l'erogatore cerca l'oggetto che ha lo stesso kid presente nell'header del voucher. In quello stesso oggetto troverà la chiave pubblica al parametro n. Effettuerà dunque una verifica della firma, che la chiave privata usata per firmare il voucher corrisponda a quella pubblica appena ottenuta.
Verifiche sul payload
Quelli che interessano ai fini della verifica sono:
- iss: l'issuer del voucher, che deve rappresentare il dominio corrispondente all'authorization server di PDND Interoperabilità che ha rilasciato il voucher stesso (ad esempio, l'issuer di produzione è interop.pagopa.it);
- exp: la scadenza del voucher;
- aud: l'audience, ossia l'indicazione di quale servizio dell'erogatore il fruitore intenda consumare con il voucher.
Best practice sulla verifica della risorsa richiesta
Le best practice emerse prevedono che l’erogatore possa fare una delle seguenti due verifiche:
- verificare l’audience (campo aud) assieme al producerId (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;
- verificare la corrispondenza di eserviceId e descriptorId (id dell'e-service e della versione di e-service) rispetto alla propria risorsa. In questa maniera si ottiene una maggiore granularità di verifica.
Per maggiori informazioni, si veda il webinar dedicato.
Pagina successiva → Come verificare la validità di un voucher DPoP
Hai bisogno di aiuto?
Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata
