Tabella dei contenuti
How to request a Bearer voucher for PDND APIs
For a list of all APIs made available by PDND, see here.
More information on this implementation is available in the dedicated section.
Essentially, the end-to-end process requires five steps:
- The consumer generates the client assertion;
- The consumer requests the voucher from the PDND authorization server;
- The PDND authorization server performs the necessary checks. If successful, it returns a voucher;
- The consumer makes a request to the PDND APIs, inserting the voucher issued by PDND in the Authorization header;
- PDND performs the necessary checks. If successful, it processes the consumer’s request.
It is assumed that the consumer has:
- created an API Interop-type client (read tutorial);
- generated at least one set of cryptographic material and uploaded the corresponding public key to PDND within the client (read tutorial).
The first step is to build a valid client assertion. The client assertion consists of a header and a payload containing the following fields.
Header:
| Field name | Meaning |
|---|---|
| kid | the ID of the key used to sign the assertion, available on PDND |
| alg | the algorithm used to sign the JWT (for now, always RS256) |
| typ | the type of object being sent (always JWT) |
Payload:
| Field name | Meaning |
|---|---|
| iss | the issuer, in this case the clientId |
| sub | the subject, in this case always the clientId |
| aud | the audience, available on PDND |
| jti | the JWT ID, a unique random ID assigned by whoever is creating the token, used to track the token itself. It is the caller’s responsibility to ensure that the ID of this token is unique for the client assertion |
| iat | issued at, the timestamp indicating when the token was created, expressed in UNIX epoch (numeric value, not a string) |
| exp | expiration, the timestamp indicating when the token expires, expressed in UNIX epoch (numeric value, not a string) |
As an example, here is a deserialized client assertion to highlight its contents.
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}
9After building a valid client assertion, it must be signed with your private key (which must match the public key uploaded to the client on PDND).
For demonstration purposes, a Python script has been published to show how to perform this operation. All instructions are available in the back office, within your client.
A function is also available to verify the validity of your client assertion and highlight any errors. This tool is available in the back office under Developers tools > Debug client assertion.
The second step is to call the PDND authorization server with the signed client assertion to obtain a voucher that can be used with the PDND APIs.
The endpoint URL of the authorization server changes depending on the environment and will be clearly visible on the back office interface.
The endpoint must be called with some parameters in the body:
| Field name | Meaning |
|---|---|
| client_id | again, the clientId used in the assertion |
| client_assertion | the signed client assertion from the first step |
| client_assertion_type | the client assertion format, as indicated in RFC (always urn:ietf:params:oauth:client-assertion-type:jwt-bearer) |
| grant_type | the type of flow used, as indicated in RFC (always client_credentials) |
If everything is set up correctly, PDND will respond with a valid voucher in the access_token property of the response body.
Also in the response, you will find the voucher’s validity duration in seconds (e.g., "expires_in": 600 means a voucher valid for 10 minutes, 10 × 60 seconds = 600). The voucher’s duration is chosen by the producer based on their security considerations.
The response returned by the PDND authorization server is as follows:
1{
2 "access_token": "eyJ0eXAiOiJhdCtqd3QiLC...",
3 "expires_in": 600
4}
5If we decode the access_token field, we get
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 - Requesting data from PDND
The voucher must be included in the header of all subsequent calls to the PDND APIs. It must be placed in the Authorization header, as follows:
1Authorization: Bearer <voucher>
2Step 5 - Wait for the response
PDND verifies the validity of the voucher (ensuring it is indeed a voucher for its APIs and that it is still valid). If so, and if the consumer’s request is well-formed, it performs the requested operation.
Hai bisogno di aiuto?
Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata
