Linee Guida OpenID Connect in SPID

Linee guida OpenID Connect in SPID

Le linee guida definiscono come integrare OpenID Connect nello SPID, sostituendo o affiancando i meccanismi già previsti dal sistema di identità digitale. Il documento disciplina in modo prescrittivo i ruoli di OpenID Provider e Relying Party, i metadata, il flusso di autenticazione, i token e i controlli di sicurezza, con regole specifiche per applicazioni web e mobile.

Ambito di applicazione, destinatari e fonti normative

Le linee guida sono adottate ai sensi dell’art. 71 del CAD e della determinazione AgID n. 160/2018. I destinatari sono i gestori dell’identità digitale e i fornitori di servizi di cui al DPCM 24 ottobre 2014, rispettivamente assimilati a OP/IdP e RP/SP ai fini del documento. L’obbligo di attuazione decorre per i gestori dal 1 maggio 2022; per i fornitori di servizi è prevista la facoltà di presentare domanda di adesione a SPID sulla base di tali regole dal 2 maggio 2022.

Quadro tecnico e standard di riferimento

Il profilo SPID OpenID Connect si fonda sul profilo iGov di OpenID Connect e sugli standard collegati di discovery, registration e core. Le linee guida richiamano anche OAuth 2.0, RFC 7009 (revocation), RFC 7636 (PKCE), RFC 7662 (introspection), RFC 8252 (native app) e le specifiche JWT/JWS/JWE pertinenti. La personalizzazione SPID prevede, tra l’altro, l’uso del solo scope openid e la distribuzione dei metadata secondo le modalità definite da AgID.

Definizioni operative e corrispondenze con SAML 2.0

Il documento evidenzia la corrispondenza concettuale tra i due ecosistemi federativi: ID Token corrisponde ad Assertion, UserInfo Endpoint ad Attribute Query, prompt=login a ForceAuthn, prompt=none a Passive Authentication, OP a Identity Provider, RP a Service Provider, claims ad attributi. Ai fini delle linee guida, OP e RP coincidono con gestori dell’identità digitale e fornitori di servizi nel quadro SPID.

Metadata dell’OpenID Provider

I metadata OP, mantenuti dal Registry SPID e distribuiti alla federazione, servono alla configurazione dei sistemi. Devono indicare:

• issuer, coincidente con il valore iss degli ID Token ed identificativo univoco dell’OP;
• authorization_endpoint, token_endpoint, userinfo_endpoint, introspection_endpoint, revocation_endpoint, end_session_endpoint;
• jwks oppure jwks_uri, secondo modalità definite da AgID;
• algoritmi supportati per firma e cifratura di request object, ID Token e UserInfo;
• token_endpoint_auth_methods_supported, che deve contenere solo private_key_jwt;
• acr_values_supported, con i livelli SPID supportati;
• request_parameter_supported, che deve essere true;
• subject_types_supported, che deve contenere pairwise;
• claims_supported, con gli attributi SPID elencati nelle linee guida;
• op_name e op_uri, anche multilingua.

L’OP deve supportare RS256 per la firma dei request object e degli ID Token, oltre ad altri algoritmi eventualmente ammessi. La scelta tra jwks e jwks_uri è rimessa alle modalità definite da AgID.

Metadata del Relying Party

I metadata RP sono analoghi e derivano dal profilo di registration OIDC. Devono includere:

• client_id, che identifica univocamente il RP nel Registro SPID;
• redirect_uris, con corrispondenza esatta rispetto alla redirect_uri usata nella request;
• jwks o jwks_uri;
• client_name, anche multilingua;
• response_types, che deve contenere solo code;
• grant_types, che deve contenere authorization_code e refresh_token.

Le redirect_uri devono essere in HTTPS; sono ammessi schemi custom per supportare app mobili. Le linee guida raccomandano di non inserire nell’URL informazioni utili a individuare il servizio specifico, privilegiando un sistema di access management intermedio, in coerenza con la disciplina privacy.

Flusso autorizzativo: solo Authorization Code Flow

L’unico flusso consentito è l’Authorization Code Flow. Il processo è articolato così:

1. l’utente seleziona sul RP l’OP con cui autenticarsi;
2. il RP invia una authentication request all’authorization endpoint dell’OP;
3. l’OP autentica l’utente e chiede, se necessario, il consenso al trasferimento degli attributi;
4. l’OP redirige verso la redirect_uri con un authorization code;
5. il RP scambia il code al token endpoint;
6. il token endpoint restituisce ID Token, access token ed eventualmente refresh token;
7. il RP usa l’access token per richiedere allo userinfo endpoint i claim autorizzati.

Per le applicazioni mobili il documento precisa che il RP coincide con l’insieme app + eventuale backend. Le richieste al token endpoint e allo userinfo endpoint possono essere inviate dall’app o dal backend; lo scambio interno non è normato, ma è raccomandata la massima sicurezza nella trasmissione e conservazione degli access token. Per l’invio della request di autenticazione sono ammessi browser o webview, purché protetti con i meccanismi più sicuri disponibili; si richiama RFC 8252 e, come raccomandazione, la libreria AppAuth.

Authentication request: requisiti sostanziali e formali

La request verso l’authorization endpoint deve contenere un oggetto JWT nel parametro request, trasmesso via GET o POST; in caso di POST si applica la form serialization. I parametri client_id, response_type e scope devono comparire sia nella chiamata HTTP sia nel request object e i valori devono coincidere; in caso di divergenza prevale il JWT.

Nella request sono obbligatori, in sintesi:

• client_id, corrispondente al Registro SPID;
• code_challenge e code_challenge_method=S256;
• nonce, stringa casuale di almeno 32 caratteri alfanumerici;
• prompt, con i valori previsti dalle linee guida (consent, consent login, verify);
• redirect_uri, tra quelle ammesse nei metadata;
• response_type=code;
• scope=openid;
• acr_values, con uno o più livelli SPID in ordine di preferenza;
• claims, per richiedere gli attributi SPID;
• state, stringa casuale di almeno 32 caratteri alfanumerici;
• eventualmente ui_locales.

Il parametro request deve essere un JWT firmato secondo le modalità definite da AgID.

Claims e richiesta degli attributi

Gli attributi SPID vanno chiesti solo tramite il parametro claims, nella sezione userinfo. Le linee guida escludono espressamente la possibilità di richiedere attributi SPID nell’ID Token. Gli attributi richiesti sono resi disponibili al momento della chiamata allo userinfo endpoint. Le richieste possono indicare ciascun claim come chiave JSON, con valore {"essential": true} oppure secondo modalità definite da AgID.

PKCE e mitigazione degli attacchi

Il documento impone l’uso di PKCE per mitigare l’intercettazione dell’authorization code, in particolare nelle app mobili. Il code_verifier e il code_challenge devono essere generati secondo le modalità definite da AgID; al token endpoint il client deve presentare il code_verifier per consentire la verifica della corrispondenza con il challenge iniziale.

Authentication response ed error handling

Se l’autenticazione ha successo, l’OP reindirizza la redirect_uri con code e state. Il state deve essere identico a quello inviato nella request e il client è tenuto a verificarne la corrispondenza.

In caso di errore, l’OP segue le tabelle di anomalia previste dalle Linee Guida UX SPID. Se è previsto il redirect, l’OP reindirizza verso la redirect_uri valida con error, error_description e state. L’error_description ha finalità di debugging e non è destinata all’utente finale.

Token endpoint: autenticazione client e contenuti della response

Il token endpoint consente due scenari: scambio dell’authorization code per ottenere ID Token e access token, oppure uso del refresh token per ottenere un nuovo access token. L’unico metodo di autenticazione client consentito è private_key_jwt.

La client assertion deve contenere almeno:

• iss e sub, coincidenti e riferiti al RP registrato;
• aud, pari all’URL del token endpoint dell’OP;
• iat e exp;
• jti, univoco e con almeno 128 bit di entropia.

La response del token endpoint include:

• access_token, in formato JWT firmato;
• token_type=Bearer;
• refresh_token, se previsto;
• expires_in;
• id_token.

L’access token serve per lo userinfo endpoint. L’ID Token deve essere validato dal client; deve contenere, tra gli altri, iss, sub, aud, acr, at_hash, iat, nbf, exp, jti e nonce. Il client deve verificare, in particolare, corrispondenza di issuer, audience, nonce e at_hash, nonché la validità temporale del token.

UserInfo endpoint e rilascio degli attributi

Lo userinfo endpoint è una risorsa protetta OAuth 2.0 che restituisce gli attributi dell’utente autenticato. È accessibile solo con metodo GET e con bearer token nell’header Authorization. La response deve avere Content-Type: application/jwt; il body deve contenere un JWT firmato e cifrato secondo le modalità definite da AgID.

Nel payload del JWT sono presenti iss, aud, iat, nbf, exp, sub e i claim autorizzati. Il RP deve verificare che:

• sub coincida con quello dell’ID Token;
• aud coincida con il proprio client_id.

In caso di errore di autenticazione, si applicano le regole di errore dello standard OpenID Connect Core.

Introspection endpoint

L’introspection endpoint consente al RP di verificare lo stato di un token in suo possesso. La request richiede il token da analizzare e una client assertion che identifichi il RP. L’OP deve verificare la validità della JWT assertion, dei singoli campi e della firma, nonché che il client_id sia noto.

La response restituisce un JSON con almeno:

• active, booleano che segnala se il token è valido;
• scope;
• exp;
• sub;
• client_id;
• iss;
• aud.

Se il token è scaduto, revocato o non emesso per il client chiamante, active deve essere false. Gli errori prevedono, tra gli altri, invalid_client, invalid_request, server_error e temporarily_unavailable.

Revocation endpoint e logout

Il revocation endpoint consente al RP di chiedere la revoca di un access token o di un refresh token. Il RP deve invocarlo quando l’utente effettua logout o quando la sessione del RP scade, secondo le proprie policy. L’OP deve revocare il token specificato e terminare l’eventuale sessione di Single Sign-On; gli altri token eventualmente attivi dell’utente restano validi.

La revoca richiede una client assertion analoga a quella usata per token e introspection. La response è sempre HTTP 200 anche se il token non esiste o è già stato revocato, al fine di non rilasciare informazioni utili.

Sessioni lunghe revocabili per applicazioni mobili

Le sessioni lunghe revocabili sono previste per applicazioni mobili che vogliano evitare il reinserimento delle credenziali SPID ad ogni avvio. Il documento limita tale funzionalità a SPID livello 1 per la sessione lunga e richiede che l’utente sia informato sin dal primo avvio. L’app deve chiedere ad ogni avvio o attivazione un PIN locale oppure un fattore biometrico memorizzato sul dispositivo.

In installazione o prima configurazione l’utente registra il fattore di autenticazione locale. In caso di accesso a funzionalità che richiedano un livello superiore a SPID 1, è necessaria una nuova autenticazione SPID al livello corrispondente.

Per ottenere il refresh token occorre includere offline_access nello scope e avere almeno https://www.spid.gov.it/SpidL1 in acr_values. Se la request contiene prompt=consent, il token endpoint restituisce anche il refresh token. Il refresh token ha validità massima di 30 giorni e può essere riutilizzato illimitatamente fino alla scadenza.

Gestione delle sessioni lunghe e revoca da interfaccia utente

Per consentire sessioni lunghe revocabili anche quando l’autenticazione originaria è stata di livello 2 o 3, è ammessa la gestione di sessioni di autenticazione distinte per livello SPID, mantenute dal gestore dell’identità digitale. Gli OP devono esporre nella pagina di gestione dell’identità SPID un’interfaccia che mostri le sessioni lunghe attive e consenta all’utente di revocarle singolarmente o in massa. In caso di modifica della password, l’OP deve consentire la revoca di tutte le sessioni lunghe attive.

Gestione dei log, conservazione e sicurezza

OP e RP devono conservare i log di ogni autenticazione per 24 mesi. Devono essere tracciati in particolare:

• rilascio di ID e access token a fronte di autenticazione;
• rilascio di refresh token a fronte di autenticazione;
• rilascio di ID e access token a fronte di utilizzo del refresh token.

Per ciascun rilascio devono essere conservati i JWT di richiesta e risposta; inoltre vanno tracciate le chiamate e le risposte verso ogni endpoint. La gestione deve avvenire nel rispetto del GDPR e del Codice Privacy, sotto la responsabilità dell’OP o del RP, con accesso riservato a personale designato ai sensi dell’art. 2-quaterdecies del Codice Privacy. Le linee guida ammettono misure di cifratura e basi dati con persistenza cifrata, e richiedono meccanismi a garanzia di integrità e non ripudio dei log.