Tabella dei contenuti
Checks on a Bearer voucher by a producer
The producer of an e-service must be able to verify the legitimacy of any request received. Below are the verifications that PDND suggests for Bearer vouchers. It is always at the producer’s discretion to decide which verifications to implement, or to add additional ones, depending on their own application architecture.
First, the producer extracts the voucher issued by PDND from the request header sent by the subscriber and deserializes it.
Example of a Bearer voucher issued by PDND, deserialized
Header:
1{
2 "typ": "at+jwt",
3 "alg": "RS256",
4 "kid": "{KID_PDND_KEY}"
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}
16Meaning of the fields
Header contains three fields:
| Nome campo | Significato |
|---|---|
| kid | The ID of the key used to sign the voucher, available in the PDND .well-known (see Signature checks below) |
| alg | The algorithm used to sign the JWT ( RS256) |
| typ | The type of object being sent (at+jwt) |
Payload contains thirteen mandatory fields:
| Nome campo | Significato |
|---|---|
| iss | The issuer — represents the domain corresponding to the PDND authorization server that issued the voucher (for example, the issuer for production is interop.pagopa.it) |
| nbf | Not before — the timestamp from which the voucher is valid, expressed in UNIX epoch (numeric value, not string). For PDND vouchers, nbf matches iat, meaning the voucher is usable immediately |
| iat | Issued at — the timestamp when the voucher was issued, in UNIX epoch (numeric). |
| exp | Expiration — the timestamp of the voucher's expiry date/time, in UNIX epoch (numeric). The voucher duration (difference between nbf and exp) depends on the value set by the producer in the e-service configuration |
| jti | The JWT ID — a unique random ID assigned by PDND |
| aud | The audience — indicates which producer service the subscriber intends to consume with the voucher. The value is set in the e-service configuration by the producer |
| sub | The subject — in this case, the ID of the client that requested the voucher from PDND |
| client_id | The unique identifier of the subscriber’s client that requested the voucher from PDND (same as sub) |
| purposeId | The unique identifier of the purpose for which the voucher is issued |
| producerId | The unique identifier of the producer of the e-service |
| consumerId | The unique identifier of the subscriber |
| eserviceId | The unique identifier of the e-service |
| descriptorId | The unique identifier of the e-service version |
NB: client_id is present in the token and uses snake case instead of camel case, in compliance with the relevant RFC.
Basic checks
Header checks
The voucher must be of type at+jwt.
Signature checks
The producer downloads the list of keys in use from a file exposed in the PDND .well-known directory. The correct URL is available in the back office interface within the tab of each e-service and varies depending on the environment (Testing, Verification, Production).
For example, https://interop.pagopa.it/.well-known/jwks.json is the URL for the Production environment well known.
In this file, the producer finds the object whose kid matches the one in the voucher header. In that same object, the public key is in parameter n. The producer then verifies that the private key used to sign the voucher matches the public key retrieved.
Payload checks
The relevant fields for verification are:
- iss: must match the PDND authorization server domain that issued the voucher (e.g., interop.pagopa.it in production).
- exp: voucher expiry date.
- aud: indicates the producer service the subscriber intends to consume with the voucher.
Best practice for checking the requested resource
Emerging best practices suggest that the producer may perform one of the following checks:
- Verify both the audience (aud) and the producerId. This ensures that the requested resource is correct and truly belongs to the producer’s organization.
- Verify the match between eserviceId and descriptorId (e-service and its version) against the producer’s resource. This provides a more granular verification.
For further information, see the dedicated webinar.
Hai bisogno di aiuto?
Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata
