Tabella dei contenuti

Come richiedere un voucher Bearer per le API di un erogatore (con informazioni aggiuntive)

Il JWS contenente le informazioni aggiuntive rispetta l'RFC 7519 e il pattern individuato, cioè quello previsto da AgID nel ModI (Audit REST 02). Per maggiori informazioni, si veda la sezione dedicata.

Il flusso in breve

In sostanza, il processo end-to-end richiede sette passaggi:

il fruitore genera un token a partire dalle informazioni aggiuntive
il fruitore calcola un hash a partire dal token;
il fruitore genera la client assertion inserendo al suo interno l'hash che si riferisce al token;
il fruitore chiede il voucher al server autorizzativo di PDND;
il server autorizzativo di PDND effettua le verifiche necessarie. In caso di esito positivo, restituisce un voucher;
il fruitore fa una richiesta verso l'e-service dell'erogatore; inserisce sia il voucher rilasciato da PDND Interoperabilità nell'header Authorization, sia il JWS con le informazioni aggiuntive generato al punto 1 nell'header AgID-JWT-TrackingEvidence;
l'erogatore effettua le verifiche necessarie. In caso di esito positivo, elabora la richiesta del fruitore.

Prerequisiti

Si assume che il fruitore abbia:

creato un client di tipo e-service (vedi tutorial);
generato almeno un set di materiale crittografico e caricato la relativa chiave pubblica su PDND Interoperabilità all'interno del client (vedi tutorial);
associato il client alla finalità per la quale vuole ottenere o inviare dati all'erogatore (vedi tutorial).

Step 1 - Generazione del token contenente le informazioni aggiuntive

Il fruitore costruisce un JWS , inserendo nell'header il kid di una chiave pubblica depositata su PDND Interoperabilità. Con la chiave privata corrispondente a quella pubblica firmerà questo JWS. Nel corpo (payload) del JWS inserisce le informazioni complementari da inviare all'erogatore.

Un JWS di esempio può avere header

1{
2  "alg": "RS256",
3  "kid": "ZmYxZGE2YjQtMzY2Yy00NWI5LThjNGItMDJmYmQyZGIyMmZh",
4  "typ": "JWT"
5}
6

NB: la chiave privata che firma e il kid della pubblica corrispondente depositata su PDND Interoperabilità non devono necessariamente essere gli stessi con i quali si firma la client assertion allo step 3.

Step 2 - Calcolare l'hash del JWS

A partire dalla codifica del JWS (ossia il JWS codificato secondo l'algoritmo inserito nell'header, in genere inizia per ey) il fruitore applica l'algoritmo di hashing SHA256 al JWS, ottenendone un hash non reversibile a lunghezza fissa.

A scopo esemplificativo, è possibile inserire in un terminale il seguente comando, previa installazione del pacchetto openssl

1echo -n {JWS} | openssl sha256
2

per ottenere l'hash del JWS. Ad esempio, a fronte del JWS esempio con codifica

1eyJhbGciOiJIUzI1NiIsImtpZCI6IlptWXhaR0UyWWpRdE16WTJZeTAwTldJNUxUaGpOR0l0TURKbVltUXlaR0l5TW1aaCIsInR5cCI6ImF0K2p3dCJ9.eyJqdGkiOiJkc2Zkc2Zkc2ZkcyIsImEiOiJiIn0.2QcY5UpoE2PgJhe1FKnHx-SZZq_NS6AKDTlfFdpVP9Q
2

si ottiene l'hash a lunghezza fissa

15db26201b684761d2b970329ab8596773164ba1b43b1559980e20045941b8065
2

NB: la flag -n che viene passata nel primo comando indica che vengano rimosse eventuali "newline" non viste dall'operatore. Un'eventuale "newline" presente nel token fa cambiare il valore dell'hash che poi non corrisponderà all'atto della verifica dell'erogatore.

Step 3 - Generazione della client assertion

Va quindi costruita una client assertion valida. La client assertion è composta da un header e un payload, contenenti i seguenti campi.

Header:

Nome campo	Significato
kid	l'id della chiave che si usa per firmare l'asserzione, reperibile su PDND Interoperabilità
alg	l'algoritmo usato per firmare il JWT (per ora, sempre RS256)
typ	il tipo di oggetto che si sta inviando (sempre JWT)

Payload:

Nome campo	Significato
iss	l'issuer, in questo caso il clientId
sub	il subject, in questo caso sempre il clientId
aud	l'audience, reperibile su PDND Interoperabilità
jti	il JWT ID, un id unico random assegnato da chi vuole creare il token, si usa per tracciare il token stesso. Deve essere cura del chiamante assicurarsi che l'id di questo token sia unico per quanto riguarda la client assertion
iat	l'issued at, il timestamp riportante data e ora in cui viene creato il token, 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)
purposeId	l'id della singola finalità per la quale si vuole ottenere un voucher, disponibile sul back office
digest	il campo digest ha due valori: alg, l'algoritmo di hashing, che è sempre SHA256; value, l'hash calcolato allo step 2

A titolo esemplificativo, di seguito un esempio di contenuto di client assertion deserializzata, in modo da evidenziarne il contenuto.

Header:

1{
2  "alg": "RS256",
3  "kid": "2MJFa7aSSveFte8ULX9U-MaaygcoL5fBIJDTXBdba64",
4  "typ": "jwt"
5}
6

Payload:

1{
2  "iss": "8e9f24ca-78f5-4c69-9e4f-0efbeac7bb2b", 
3  "sub": "8e9f24ca-78f5-4c69-9e4f-0efbeac7bb2b",
4  "aud": "auth.interop.pagopa.it/client-assertion",
5  "jti": "23387ac1-c192-4573-8350-207a4213d4be",
6  "iat": 1616170068,
7  "exp": 1616170668,
8  "purposeId": "34f1624b-91cb-4b05-b8c0-cad208a30222",
9  "digest": {
10    "alg": "SHA256",
11    "value": "5db26201b684761d2b970329ab8596773164ba1b43b1559980e20045941b8065"
12  }
13}
14

Dopo aver costruito una client assertion valida, questa deve essere firmata con la propria chiave privata (che deve essere l'omologa della chiave pubblica depositata sul client su PDND Interoperabilità).

A scopo esemplificativo, è stato pubblicato uno script Python per dimostrare come eseguire l'operazione. Tutte le istruzioni sono disponibili nel back office, all'interno del proprio client.

È inoltre disponibile una funzione per verificare la validità della propria client assertion ed evidenziare eventuali errori. Lo strumento è disponibile nel back office su Tool per lo sviluppo > Debug client assertion.

Step 4 - Richiedere il voucher al server autorizzativo

Il secondo passaggio è chiamare il server autorizzativo di PDND Interoperabilità con la client assertion firmata per ottenerne in cambio un voucher spendibile presso le API di PDND Interoperabilità.

L'URL dell'endpoint alla quale si trova il server autorizzativo cambia in funzione dell'ambiente in cui ci si trova e sarà chiaramente visibile sull'interfaccia all'interno del back office.

L'endpoint andrà chiamato con alcuni parametri nel body:

Nome campo	Significato
client_id	di nuovo il clientId usato nell'assertion
client_assertion	il contenuto dell'asserzione firmata nel primo passaggio
client_assertion_type	il formato della client assertion, come indicato in RFC (sempre urn:ietf:params:oauth:client-assertion-type:jwt-bearer)
grant_type	la tipologia di flusso utilizzato, come indicato in RFC (sempre client_credentials)

Step 5 - Il server autorizzativo verifica, e rilascia il voucher

Se tutto è impostato correttamente, PDND Interoperabilità risponderà con un voucher valido all'interno del body della risposta alla proprietà access_token.

Sempre nella risposta, sarà contenuta anche la durata di validità del voucher in secondi (es. "expires_in": 600 indica un voucher con validità 10 minuti, 10 * 60 secondi = 600). La durata del voucher è scelta dall'erogatore sulla base delle proprie considerazioni di sicurezza, e può variare da e-service a e-service.

La risposta che il server autorizzativo di PDND Interoperabilità restituisce è la seguente:

1{
2  "access_token": "eyJ0eXAiOiJhdCtqd3QiLC...",
3  "expires_in": 600
4}
5

Se decodifichiamo il campo dedicato all'access_token, troviamo

Header:

1{
2  "typ": "at+jwt",
3  "alg": "RS256",
4  "kid": "{KID_CHIAVE_PDND}"
5}
6

Payload:

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  "digest": {
16    "alg": "SHA256",
17    "value": "5db26201b684761d2b970329ab8596773164ba1b43b1559980e20045941b8065"
18  }
19}
20

Step 6 - Richiedere i dati all'ergoatore

Il voucher andrà inserito nell'header di tutte le chiamate successive verso le API dell'erogatore. Andrà inserito come header, come segue:

Authorization: Bearer <voucher>

Inoltre, il JWS creato allo step 1 andrà inserito all'interno di un altro header della chiamata, codificato da AgID come segue

Agid-JWT-TrackingEvidence: <jws>

Step 7 - Attendere le verifiche dell'erogatore

L'erogatore effettua tutte le verifiche necessarie. Se tutto è in ordine, elabora la richiesta del fruitore, restituendogli i dati richiesti in caso di e-service che eroga dati, oppure accettando i dati dal fruitore in caso di e-service che riceve dati.

Per consultare le verifiche consigliate agli erogatori, si veda la sezione dedicata. Inoltre, è possibile consultare le verifiche da fare per quanto riguarda il digest, specifico di questo flusso, nella sezione dedicata.

Pagina successiva → Come richiedere un voucher Bearer per le API di un erogatore (con informazioni aggiuntive)

In questa pagina

Il flusso in breve

Prerequisiti

Step 1 - Generazione del token contenente le informazioni aggiuntive

Step 2 - Calcolare l'hash del JWS

Step 3 - Generazione della client assertion

Step 4 - Richiedere il voucher al server autorizzativo

Step 5 - Il server autorizzativo verifica, e rilascia il voucher

Step 6 - Richiedere i dati all'ergoatore

Step 7 - Attendere le verifiche dell'erogatore