Procedura tecnica

Il sistema SPID si basa sul protocollo SAML2. Per implementare SPID nei tuoi servizi online:

1 ) Consulta le regole tecniche, gli avvisi SPID e la tabella anomalie, con le indicazioni necessarie a guidarti durante l'implementazione di SPID e le linee guida interfacce e informazioni per rendere riconoscibile agli utenti l’accesso con SPID ai tuoi servizi.

2 ) Implementa l'autenticazione con SPID ai tuoi servizi. Su Developers Italia sono disponibili librerie per i diversi linguaggi di programmazione e risorse utili per l’integrazione ai quali puoi fare riferimento.

Alcuni consigli utili per una migliore esperienza dell’utente:

- scrivi eventuali messaggi di errore con un testo chiaro, semplice, non tecnico e rendi disponibile un bottone per tornare indietro;
- mantieni la stessa esperienza utente (a partire dall’interfaccia grafica) anche in caso di errori o problemi tecnici;
- indica correttamente le “anomalie SPID” così come indicato nella tabella anomalie;
- accertati che sia sempre presente un bottone “Logout” per poter uscire, una volta autenticati, dal servizio;
- prevedi per l’utente l’accesso ai servizi anche tramite credenziali SPID di livelli superiori a quello minimo richiesto.

3 ) Verifica se la tua organizzazione ha già prodotto ed inviato ad AgID un metadata. In caso affermativo modifica il metadata già presentato per includere i nuovi servizi, altrimenti elabora un metadata come indicato nel documento riassuntivo ( secondo le indicazioni contenute nell' Avviso n.6, ed in particolare nell' Avviso n.19 v.4 e nell' Avviso n.29 v.3 ). Gli attributi richiesti per l'erogazione di ogni servizio online, inoltre, devono essere attinenti e non eccedenti.

4 ) Verifica autonomamente la correttezza del metadata e la tua implementazione.
Prima di effettuare i passaggi successivi, puoi installare e configurare in locale lo SPID Validator, disponibile sul sito GitHub Italia, e utilizzarlo per pre-collaudare la tua implementazione. Oppure puoi utilizzare l'ambiente Demo / Validator disponibile online su https://demo.spid.gov.it configurando sul tuo SP:
- il metadata dell'ambiente Demo online
- e il metadata dell'ambiente Validator online

Alcune indicazioni utili:

- Con SPID Validator puoi simulare il controllo di AgID e puoi ottenere autonomamente e in maniera rapida un’implementazione conforme dal punto di vista tecnico.
- Verifica il corretto funzionamento per ognuno dei test indicati nel documento SPID Quality Assessment Document.

Puoi procedere con l’accreditamento come fornitore di servizi solo una volta superati i controlli previsti dallo SPID Validator. Superati i controlli, il collaudo effettuato da AgID è l’ultima verifica per abilitare l’accesso ai servizi con SPID.

Si raccomanda di disattivare sul Service Provider, prima di inviare la richiesta di collaudo, ogni configurazione (comprendente il certificato di verifica della firma delle asserzioni) ulteriore non relativa agli IdP ufficiali con la sola eccezione del collegamento al Validator ufficiale (https://validator.spid.gov.it), la cui configurazione dovrà essere attiva esclusivamente per il tempo necessario all'esecuzione del collaudo. Le richieste di collaudo relative a Service Provider che presenteranno nel bottone "Entra con SPID", collegamenti aggiuntivi verso IdP di validazione o di test diversi dal Validator ufficiale, non saranno prese in carico.

5 ) Rendi disponibile il metadata su una url 'https' del tuo dominio e inserisci tra gli IDP del bottone “Entra con SPID” anche l’IDP del tool SPID Validator (il metadata è disponibile all’url: https://validator.spid.gov.it/metadata.xml).
Il metadata deve contenere un certificato self-signed relativo alla chiave privata con cui firmare lo stesso metadata e le request verso gli IdP.
In seguito, invia una email a spid.tech@agid.gov.it (non è una casella PEC, perciò utilizza un indirizzo istituzionale di posta elettronica ordinaria) indicando le seguenti informazioni:

a) Nome ente (denominazione o ragione sociale) e alternativamente:
- se soggetto pubblico, Codice IPA
- se soggetto privato, Codice Fiscale o P.IVA
b) URL del metadata;
c) Se si tratta di aggiornamento o nuovo metadata;
d) URL del servizio al quale è presente in bottone “Entra con SPID” con il collegamento a SPID Validator;
e) Contatto riferimento tecnico (nominativo, e-mail, num. di telefono);
f) Contatto referente amministrativo (nominativo, e-mail, num. di telefono);

Se sei un fornitore di servizi privato, dovrai indicare anche:
- la descrizione dei servizi digitali che verranno resi disponibili con SPID e la tipologia di utenti cui sono destinati.

6 ) AgID provvede a verificare il metadata ricevuto e la correttezza dell’implementazione. Se necessario, saranno segnalate le modifiche utili a garantire il rispetto delle regole tecniche. La verifica condotta da AgID è eseguita tramite la piattaforma SPID SAML Check, di cui fa parte il tool SPID Validator. Il codice della piattaforma SPID SAML Check è disponibile pubblicamente al repository https://github.com/italia/spid-saml-check.

7 ) Se AgID richiede delle modifiche dovrai ripetere la procedura a partire dal punto 3.

8 ) Se l'invio del metadata e la verifica tecnica danno esito positivo, AgID comunica il metadata ai gestori d’identità. La richiesta di caricamento configurazioni agli IDP è effettuata ogni giorno, di norma alle ore 18.00, dal lunedì al venerdì. Di norma, entro un giorno lavorativo, gli IDP provvedono al loro caricamento ed il servizio sarà accessibile tramite SPID.

Se sei un fornitore di servizi privato, dovrai prima richiedere un certificato ad AgID con il quale firmare il tuo metadata ed inviarcelo per la messa in produzione.