Technical procedure
The SPID system is based on the SAML2 protocol. To implement SPID in your online services:
1 ) See the technical rules, SPID alerts and anomaly table, along with the necessary indications to guide you during SPID implementation and interface guidelines and information to make SPID access to your services recognizable to users.
2 ) Implement SPID authentication for your services. On Developers Italia there are libraries for different programming languages and useful resources for integration that you can refer to.
For a better user experience:
- write any error messages with a clear, simple, non-technical text and make available a button to go back;
- maintain the same user experience (starting from the graphical interface) even in case of errors or technical problems;
- correctly point out the "SPID anomalies" as indicated in the anomalies table;
- make sure that there is always a "Logout" button to exit from the services, once authenticated;
- provide the user access to services also through SPID credentials of higher levels than the minimum required;
3 ) check if your organization has already produced and sent a metadata to AgID. If so, modify already submitted metadata to include new services, otherwise elaborate a metadata as indicated in the summary document (according to the indications contained in the Notice n.6, and in particular in Notice n.19 v.4 and Notice n.29 v.3). Moreover, the attributes required for the provision of each online service must be relevant and not excessive;
4 ) independently check the accuracy of the metadata and your implementation;
before proceeding with the following steps, you can install and configure the SPID Validator, available online on GitHub Italia website, and use it to pre-test your implementation. Or you can try the Demo/Validator version available on https://demo.spid.gov.it setting on your SP the following items:
- the demo version metadata
- the online validator version metadata
Some useful indications:
- With SPID Validator you can simulate the AgID audit and can independently and quickly obtain a technically compliant implementation.
- Check the correct functioning for each of the tests indicated in the SPID Quality Assessment Document.
You can proceed with accreditation as a service provider only once you have passed the checks required by the SPID Validator. Once passed the checks, the test carried out by AgID is the last verification to enable access to services with SPID.
Before sending the test request, It’s recommended to deactivate on the Service Provider any additional configuration (including the assertion signature verification certificate) not related to the official IdPs with the sole exception of the connection to the official Validator (https://validator.spid.gov.it), configuration of which must be active only for the time necessary to perform the test. The test requests relating to Service Providers that will present in the “Enter with SPID” button, additional links to the IdP for validation or tests other than the official Validator, will not be taken into account.
5) Finally, make the metadata available on an 'https' url of your domain and insert the IDP of the SPID Validator tool among the IDPs of the "Log in with SPID" button (the metadata is available at the url: https://validator.spid.gov.it/metadata.xml).
The metadata must contain a self-signed certificate related to the private key with which to sign the metadata and the requests to the IdP.
Afterwards, send an e-mail to spid.tech@agid.gov.it (it is not a PEC box, therefore use an ordinary institutional email address) indicating the following information:
a) Entity name (name or company name) and alternatively:
- IPA Code (Codice IPA) if public entity,
- Tax Code or VAT number (Codice Fiscale o P.IVA) if a private person.
b) URL of the metadata;
c) Weather it is an update or a new metadata;
d) URL of the service where there is the "Login with SPID" button with the link to SPID Validator;
e) Technical reference contact (name, e-mail, phone number);
f) Administrative contact (name, e-mail, phone number);
If you are a private service provider, you must also indicate the description of the digital services that will be made available with SPID and the type of users they are intended for.
6) AgID will verify the received metadata and the accuracy of the implementation. If necessary, changes will be reported to ensure compliance with the technical rules. The verification conducted by AgID is performed through the SPID SAML Check platform, which includes the SPID Validator tool. The code of the SPID SAML Check platform is publicly available at the GitHub repository.
7) If AgID requests changes you will have to repeat the procedure starting from point 3.
8) If the submission of the metadata and the technical verification are successful, AgID communicates the metadata to the identity providers. The request for uploading configurations to IDPs is made every day, at 18:00.00, from Monday to Friday. within one working day, IDPs will upload them and the service will be accessible through SPID.