Tabella dei contenuti
Types of voucher requests
It is possible to request vouchers from PDND that comply with different specifications. For all the cases listed below except the first, the voucher to request is detailed by the producer in the settings of their e-service (API interface file and attached technical documentation). If the producer does not specify anything, the voucher to produce is of the second type (Bearer) without additional information.
The possible types are as follows:
- Bearer voucher usable with PDND APIs;
- Bearer voucher usable with a producer's APIs;
- DPoP voucher usable with a producer's APIs.
For options 2 and 3, both a standard configuration and one including additional information are possible, according to the pattern described by AgID called Audit REST 02.
Below is a brief description of all voucher types.
Basic request flow
In all cases, the voucher request consists of at least three steps:
- generating and signing a client assertion that provides the request details (from which client, for which purpose, etc.);
- sending the client assertion to PDND’s authorization server which, after verification, issues the voucher;
- sending the data request to the producer, including in the request header the voucher obtained from PDND.
All the request types are variations of this flow and refer to specific RFCs.
The signing and verification process follows international specifications that ensure security. The reference standards include:
- RFC 8017 (PKCS #1): defines the methods for using the RSA algorithm for digital signatures;
- RFC 7518 (JSON Web Algorithms): specifies signature algorithms such as RSA and SHA-256;
- RFC 7517 (JSON Web Key — JWK): specifies the JSON format for representing cryptographic keys, both public and private.
Bearer Token usable with PDND APIs
It has two distinctive features:
- it must be made by a PDND API client;
- it does not require specifying the reference purpose.
The PDND APIs are provided to all parties by contract, as required by AgID Guidelines. For this reason, there is no need to detail the purpose of the request.
The list of APIs exposed by PDND is available here.
For more information, see the practical tutorial.
Bearer Token usable with a producer's APIs (standard)
Used by the vast majority of services, it requires creating a client assertion detailing the basic information requested by PDND. This is useful both for audit purposes and for allowing the producer to assess the incoming data access requests.
For more information, see:
- subscriber side: the practical tutorial for requesting a voucher;
- producer side: the recommended standard checks.
Bearer Token usable with a producer's APIs (with additional information — ModI Audit REST 02pattern)
Used by all those services for which the producer considers it necessary to obtain additional audit information not included in the standard fields required by PDND within the client assertion.
An example might be the caller's IP address or information related to the operator making the request.
The mechanism allows the producer to verify that the subscriber has deposited a record on PDND, which acts as a notary in this process. At the same time, the information is exchanged directly between subscriber and producer, without PDND knowing it.
An example of this pattern is the ANPR services.
In this flow, the subscriber forges a second JWT containing the additional information. From this JWT, a hash is derived, which is then included in the client assertion in the digest.value field.
Finally, after obtaining a voucher from PDND, the subscriber includes both the voucher and the second JWT in the call to the producer. The producer then compares the hash found in the digest in the PDND voucher with a value calculated from the contents of the second JWT. If they match, the additional data in the second JWT is intact.
For more information, see:
- subscriber side: the practical tutorial for requesting a voucher;
- producer side: the recommended standard and additional checks.
DPoP usable with a producer's APIs (standard)
The Demonstrating Proof-of-Possession (DPoP) pattern involves using two DPoP tokens, one for PDND and the other for the resource server from which the data is being requested. If the two independent verifications do not match, the request is not authorized.
This pattern provides an additional security layer, useful for example when the data is requested for a single specific operation, such as when a device requests authorization to access data.
It is a valid alternative to mTLS in some cases, with the advantage of not requiring a certificate exchange between the two parties and not needing special maintenance, especially by the producer.
For more information, see:
- subscriber side: the practical practical tutorial for requesting a voucher;
- producer side: the recommended standard checks;
- everyone: the dedicated in-depth guide.
DPoP usable with a producer's APIs (with additional information — ModI Audit REST 02pattern)
This mirrors the previous DPoP case, but includes the additional information a producer may require, as described in the earlier case.
For more information, see:
- subscriber side: the practical tutorial for requesting a voucher;
- producer side: the recommended standard and additional checks;
- everyone: the dedicated in-depth guide.
In questa pagina
Basic request flow
Security and reference standards for signing and verification
Bearer Token usable with PDND APIs
Bearer Token usable with a producer's APIs (standard)
Bearer Token usable with a producer's APIs (with additional information — ModI Audit REST 02pattern)
DPoP usable with a producer's APIs (standard)
DPoP usable with a producer's APIs (with additional information — ModI Audit REST 02pattern)
Hai bisogno di aiuto?
Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata
