Table of contents
How to prepare the certification environment
Step 1: Access to the environment
To access the certification environment, it is necessary to perform the onboarding procedure via this link:
Once access is obtained, perform the login using SPID or CIE, directly on the portal:
Logging in and selecting the institution accesses the platform from which it is possible, via the reserved area, to access the desired environment.
Clicking “Enter” provides access to all the functions provided on the portal.
Step 2: Subscribing to an e-service
The first step in order to use all the potentials of an e-service is to subscribe to it.
By navigating the menu, go to Usage > e-service catalog and select the service that best fits your needs (see Tutorial to find what is appropriate for you)
Once identified, access it and select the button “Request usage” located on the right side.
Follow the procedure until performing the “Forward request” action.
When the request for usage is approved and activated, you can proceed with creating the purposes.
Step 3: Creation of a purpose
To create a new purpose, access the menu item “Usage > Your purposes”.
Click the “Create new” button.
At this point, follow the guided procedure for creation.
Each purpose is associated with one of the e-services you registered for.
For each of them, define a purpose and the method with which you will use it (e.g. number of calls during a day).
With an active purpose, you can implement the flow to obtain a voucher you can spend via the API of the provider.
Step 4: Creation of a client
Once the two previous steps have been completed, proceed with the creation of a client that will connect the various entities.
From the menu located on the left side, access the section “Usage> Your e-service clients”.
Follow the guided procedure. You will be requested to select also a public key.
If you do not know how to perform the step for uploading the public key, follow the guide at this link.
The step for creating the client and in particular the public key is a fundamental step for obtaining the voucher that can be spent with the selected e-services.
The vouchers are in fact JWT tokens (JSON Web Token). Authentication follows the OAuth 2.0 flow.
It is possible to use the Keychain creation function allow authorized users to save a list of public keys to upload to the certification platform. These keys can be used by the users to verify the integrity of the response received from the provider following a request on the e-service that integrates that functionality, without changes to the invocation of the e-service.
It is possible to create the keychain by accessing the menu item “Provision > Your keychains”.
Step 5: Generation of the voucher
The first step consists in creating a valid client assertion and signing it with the private key, which must correspond to the public key deposited in the section “Your e-service clients”. The client assertion is comprised of two main parts: a header and a payload.
Three fields are inserted in the header:
- kid: the ID of the key used to sign the assertion, which can be found in your client area, under the section “Client assertion”;
- alg: the algorithm used to sign the JWT (insert RS256);
- typ: the type of object you are sending (insert JWT).
There will be instead the following fields in the payload:
- iss: the issuer, i.e. the clientId;
- sub: the subject, also in this case it is the clientId;
- aud: the audience, can also be found in the section dedicated to your client;
- purposeId: the ID of the purpose;
- jti: the JWT ID, a random univocal ID generated by the caller;
- iat: issued at, the timestamp with the date and time that token is created, expressed in UNIX epoch (numeric value, non-string);
- exp: expiration, the timestamp with the date and time of token expiration, expressed in UNIX epoch (numeric value, non-string).
Once the assertion is signed, take the output and keep it available.
The second step is to call the authorizing server of PDND Interoperability with the client assertion to obtain in exchange a voucher that can be spent with the desired e-service.
The URL of the endpoint for the certification environment is as follows:
https://auth.att.interop.pagopa.it/token.oauth2
The endpoint must be invoked with the following parameters in the body of the request:
- client_id: the clientId used in the assertion;
- client_assertion: the content of the signed assertion obtained in the first step;
- client_assertion_type: the format of the client assertion, as indicated in RFC (it will always be urn:ietf:params:oauth:client-assertion-type:jwt-bearer);
- grant_type: the type of flow used, as indicated in RFC (always client_credentials).
If all the steps were performed correctly, PDND Interoperability will respond with a valid voucher in the body of the response.
Specifically, the voucher will be located in the access_token property. The response also contains the duration of token validity in seconds (e.g. "expires_in": 600 indicates a token that is valid for 10 minutes, 10 x 60 seconds = 600).
The obtained token must be inserted in the header Authorization: Bearer for all calls made to the e-service.
