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 incoming request. Below are the verifications recommended by the National Digital Data Platform (PDND) for Bearer vouchers. Each producer may decide which checks to implement—or add others—according to their own application architecture.

First, the producer extracts the voucher issued by PDND from the header of the consumer’s request 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}
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}
16
17

Meaning of the fields

Header fields

Field	Meaning
kid	ID of the key used to sign the voucher, retrievable from PDND’s well-known endpoint (see Signature verification).
alg	Algorithm used to sign the JWT (RS256).
typ	Type of object being sent (at+jwt).

Payload fields

Field	Meaning
iss	Issuer — corresponds to the domain of PDND’s authorization server that issued the voucher (e.g., interop.pagopa.it in the production environment).
nbf	Not before — timestamp from which the voucher is valid, expressed in UNIX epoch. For PDND vouchers, this matches iat, meaning the voucher is immediately usable.
iat	Issued at — timestamp when the voucher was issued, in UNIX epoch.
exp	Expiration — timestamp indicating the voucher’s expiration time, in UNIX epoch. The duration (difference between nbf and exp) depends on the value configured by the producer in the e-service settings.
jti	JWT ID — a unique identifier assigned by PDND.
aud	Audience — indicates which producer’s service the consumer intends to access with the voucher. The value corresponds to what the producer entered in the e-service configuration.
sub	Subject — the ID of the client that requested the voucher from PDND.
client_id	Unique identifier of the consumer’s client that requested the voucher from PDND (same as sub).
purposeId	Unique identifier of the purpose for which the voucher was issued.
producerId	Unique identifier of the e-service producer.
consumerId	Unique identifier of the consumer.
eserviceId	Unique identifier of the e-service.
descriptorId	Unique identifier of the e-service version.

Note: The client_id field in the token uses snake case instead of camel case, in compliance with the relevant RFC.

Basic verifications

Header checks

The voucher must be of type at+jwt.

Signature verification

The producer downloads the list of keys used by PDND from a file exposed under its .well-known directory. The correct URL is displayed in the front office within each e-service’s technical details section and varies by environment (testing, validation, production).

For example: https://interop.pagopa.it/.well-known/jwks.json — production environment.

Inside the file, the producer locates the object whose kid matches the voucher’s header value. That object contains the public key in the n parameter. The producer then verifies that the private key used to sign the voucher corresponds to the retrieved public key.

Payload checks

The following fields are key for verification:

iss: must match the domain of PDND’s authorization server that issued the voucher (e.g., interop.pagopa.it in production).
exp: voucher expiration time.
aud: identifies the producer’s service that the consumer intends to use.

Best practices for resource verification

Recommended best practices suggest that producers perform one of the following checks:

Verify both the aud (audience) and producerId. This ensures that the requested resource is the correct one and that it actually belongs to the producer’s organization.
Verify the match between eserviceId and descriptorId (e-service ID and e-service version ID). This provides more granular validation.

For more details, see the dedicated webinar.

Next page → Checks on a DPoP voucher by a producer

Hai bisogno di aiuto?

Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata

Dicci cosa ne pensi

Per segnalare problemi o dare feedback, puoi aprire una segnalazione su Github

PDND Interoperabilità