SPID e CIE per un sito o servizio web: cosa serve tecnicamente per integrarli

Chi gestisce un sito o un servizio web prima o poi riceve la richiesta: «possiamo far entrare gli utenti con SPID?». La risposta tecnica è sì, ma l'integrazione non è un pulsante da incollare. Servono un protocollo, certificati, metadata, un passaggio formale con l'ente che governa il sistema e dei test. Questo articolo mette in fila le cose da sapere prima di iniziare. Le fonti sono quelle ufficiali: le regole tecniche su docs.italia.it, le pagine di AgID e di spid.gov.it, il portale della federazione CIE.

Prima domanda: sei obbligato?

Secondo la pagina ufficiale di SPID, tutte le pubbliche amministrazioni devono rendere accessibili i propri servizi online con SPID e CIE. Per i soggetti privati l'attivazione è facoltativa. Questa distinzione cambia il percorso: i privati firmano una convenzione con AgID e, come vedremo, possono anche passare da un intermediario.

Il protocollo: SAML2 oppure OpenID Connect

SPID nasce su SAML 2.0, ed è lo standard che la pagina di AgID per diventare fornitore di servizi indica per l'integrazione nelle applicazioni web. Le regole tecniche SAML descrivono, tra le altre cose, il metadata del Service Provider, i binding HTTP-Redirect e HTTP-POST, il Single Sign-On e il Single Logout. Alcuni requisiti che contano subito:

• Chiavi RSA di almeno 2048 bit e firma dei metadata con digest SHA-256 o superiore.
• TLS 1.2 obbligatorio in ambito SPID.
• Metadata con EntityID, certificato, almeno un AssertionConsumerService con binding HTTP-POST, dati dell'organizzazione e un contatto di tipo «other». Per i privati serve anche il contatto di fatturazione (billing).

Dal 2023 esistono anche le regole tecniche OpenID Connect per SPID e CIE, pubblicate su docs.italia.it e rivolte a fornitori di servizi pubblici e privati, identity provider e aggregatori. Il profilo si basa su OpenID Connect Core, sul profilo iGov e su OpenID Connect Federation 1.0. In pratica il Relying Party deve:

• inviare la richiesta di autenticazione come request object firmato (JWT);
• usare PKCE (code challenge e code verifier);
• autenticarsi al token endpoint con private_key_jwt;
• supportare almeno RS256 e RS512 per la firma, con chiavi RSA da 2048 bit in su (4096 raccomandati).

Attenzione però: la pagina di AgID per diventare fornitore SPID cita come standard di integrazione solo SAML 2.0 e non menziona OIDC. Prima di scegliere, verifica con AgID e con la tua federazione di riferimento quale strada è attivabile per il tuo caso. Se non hai vincoli, parti dal protocollo che il tuo stack supporta meglio con librerie mantenute.

Federazione, metadata e onboarding

Una federazione di identità è un insieme di organizzazioni che aderiscono allo stesso quadro regolatorio, con convenzioni e un'autorità super partes. Nella federazione SPID l'autorità è AgID, in quella CIE è il Ministero dell'Interno. Nel modello OIDC la fiducia si costruisce così:

• pubblichi la tua Entity Configuration all'indirizzo .well-known/openid-federation;
• completi la procedura amministrativa presso l'autorità di federazione o un suo intermediario;
• dopo i controlli ricevi un Trust Mark, che devi includere nella tua configurazione come prova di adesione.

Nel modello SAML il passaggio equivalente è la consegna del metadata: per SPID, dopo controlli di AgID, collaudo e firma della convenzione, AgID lo comunica ai gestori di identità. Se il tuo servizio richiede il secondo o il terzo livello di sicurezza, devi anche implementare il nodo italiano eIDAS, per consentire l'accesso ai cittadini UE.

Per CIE la pagina ufficiale descrive un percorso sul portale di federazione: registrazione e richiesta di adesione, indicazione di un partner tecnologico (una PA o un privato che facilita l'ingresso), verifica dei dati e federazione dei metadata. I dettagli stanno nel Manuale Tecnico e nel Manuale Operativo.

Costi e aggregatori

Per i cittadini l'identità digitale è gratuita. Per un fornitore privato la convenzione con AgID prevede una tabella dei corrispettivi (allegato 4), che AgID pubblica per ogni periodo di fatturazione. Non riporto cifre: cambiano e vanno lette sul documento in vigore. A questo si aggiunge il lavoro interno di sviluppo, test e manutenzione di certificati e metadata, che spesso pesa più della tariffa.

Chi non vuole costruire tutto può usare un soggetto aggregatore. Le regole tecniche distinguono due modalità: l'aggregatore light registra fornitori che hanno già un'integrazione conforme, quello full costruisce l'interfaccia di autenticazione e federazione per conto degli aggregati. È una scelta di comodo e di responsabilità: deleghi l'infrastruttura, ma accetti un'altra parte nel flusso e un contratto con condizioni proprie.

Come testare prima di andare in produzione

AgID mantiene spid-saml-check, una suite per i Service Provider: spid-sp-test verifica la conformità, spid-validator offre l'interfaccia web e spid-demo è un identity provider di prova con utenti fittizi. Si avvia con Docker. Il validator esegue oltre 300 controlli su metadata, richieste e risposte. Per l'OIDC esistono implementazioni di riferimento open source, per esempio spid-cie-oidc-django. Se l'errore è una firma che non torna, trovi un percorso di diagnosi in SAML in Nextcloud: errore di validazione della firma.

Alternative quando SPID e CIE non servono

Se il servizio non è tenuto a usare SPID e non serve identificare cittadini con valore legale, valuta se ti basta altro:

• Login proprio con password forte e secondo fattore, o passkey.
• Provider esterni (Google, Microsoft) via OpenID Connect, se il tuo pubblico li usa già.
• Un identity provider tuo (per esempio Keycloak) davanti alle applicazioni, per tenere un solo punto di accesso. Un'esperienza concreta di SAML e OIDC con Nextcloud è in 8 errori che tornano sempre nel supporto.

Queste soluzioni non sostituiscono SPID dove la legge o il cliente lo richiedono: vanno bene quando serve solo un accesso comodo e sicuro.

Checklist finale

• Verifica se sei tenuto a usare SPID e CIE (PA) o se è una scelta (privato).
• Scegli il protocollo e conferma con AgID che sia attivabile nel tuo caso.
• Prepara certificati RSA da almeno 2048 bit e TLS 1.2 sul sito.
• Redigi il metadata con tutti i campi obbligatori e un contatto non riferito a una persona fisica.
• Leggi la tabella dei corrispettivi in vigore e stima i costi interni.
• Decidi se fare da solo o passare da un aggregatore (light o full).
• Nomina un referente tecnico e un rappresentante legale per la convenzione.
• Valuta il nodo eIDAS se servono i livelli 2 o 3.
• Testa con spid-saml-check prima di consegnare i metadata.
• Per CIE, registrati sul portale di federazione e leggi i manuali.
• Pianifica la scadenza dei certificati e il monitoraggio del login.

Le regole cambiano e le pagine ufficiali si aggiornano: usa questo articolo come mappa e le fonti di AgID, del Ministero dell'Interno e di docs.italia.it come riferimento finale.