Tabella dei contenuti
Come richiedere un voucher Bearer per le API di PDND Interoperabilità
Per un elenco di tutte le API messe a disposizione da PDND Interoperabilità, si veda qui.
Maggiori informazioni su questa implementazione nella sezione dedicata.
In sostanza, il processo end-to-end richiede cinque passaggi:
- il fruitore genera la client assertion;
- 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 le API di PDND Interoperabilità; inserisce il voucher rilasciato da PDND Interoperabilità nell'header Authorization;
- PDND Interoperabilità effettua le verifiche necessarie. In caso di esito positivo, elabora la richiesta del fruitore.
Si assume che il fruitore abbia:
- creato un client di tipo API Interoperabilità (vedi tutorial);
- generato almeno un set di materiale crittografico e caricato la relativa chiave pubblica su PDND Interoperabilità all'interno del client (vedi tutorial).
Il primo passo è costruire 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) |
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}
6Payload:
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}
9Dopo 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 2 - 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 3 - 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.
La risposta che il server autorizzativo di PDND Interoperabilità restituisce è la seguente:
1{
2 "access_token": "eyJ0eXAiOiJhdCtqd3QiLC...",
3 "expires_in": 600
4}
5Se decodifichiamo il campo dedicato all'access_token, troviamo
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": "api.interop.pagopa.it/v2",
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}
16Step 4 - Richiedere i dati a PDND Interoperabilità
Il voucher andrà inserito nell'header di tutte le chiamate successive verso le API di PDND Interoperabilità. Andrà inserito nell'header di Authorization, come segue:
1Authorization: Bearer <voucher>
2Step 5 - Attendere la risposta
PDND verifica la validità del voucher (che sia effettivamente un voucher per le proprie API, e che sia in corso di validità). In quel caso, se la richiesta del fruitore è ben formattata, esegue l'operazione richiesta.
Pagina successiva → Come richiedere un voucher Bearer per le API di un erogatore (base)
Hai bisogno di aiuto?
Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata
