Scopo¶

Le Linee Guida vengono emesse ai sensi dell’articolo 71 del decreto legislativo 7 marzo 2005, n. 82 e successive modifiche e integrazioni (di seguito CAD) e della Determinazione AgID n. 160 del 2018 recante «Regolamento per l’adozione di linee guida per l’attuazione del Codice dell’Amministrazione Digitale».

OpenID Connect è un layer di identità basato su JSON/REST che si posiziona sopra al protocollo OAuth 2.0. La sua filosofia di design è «rendi semplici le cose semplici e rendi possibili le cose complicate». Mentre OAuth 2.0 è un protocollo di delega delle autorizzazioni di accesso generico, consentendo così il trasferimento di dati arbitrari e non definisce i modi per autenticare gli utenti o comunicare informazioni su di essi, OpenID Connect offre un layer di identità sicuro, flessibile e interoperabile in modo che le identità digitali possano essere facilmente utilizzate su servizi desktop e mobile.

OpenID Connect non si occupa solo di autenticazione ma può essere anche utilizzato per autorizzazione, delega e API access management.

I suoi punti di forza sono:

• facilità di integrazione;
• abilità di integrare applicazioni su diverse piattaforme, single-page app, web, backend, mobile, IoT;
• permette integrazione di componenti di terze parti in modalità sicura, interoperabile e scalabile;
• risolve diverse problematiche di sicurezza riscontrate in OAuth 2.0;
• è utilizzato da un gran numero di servizi social e di pagamento.

Per tutti questi motivi, le presenti linee guide intendono normare l’utilizzo di OpenID Connect nel Sistema Pubblico di Identità Digitale italiano (SPID).

Gruppo di lavoro¶

La redazione del documento è stata curata dal gruppo di lavoro composto da:

• Agenzia per l’Italia Digitale;
• Agenzia delle Entrate;
• Aruba S.p.A.;
• Comune di Roma;
• CSI Piemonte;
• Infocert S.p.A.;
• INPS;
• In.Te.S.A. S.p.A.;
• Istituto Poligrafico e Zecca dello Stato;
• Lepida S.p.A.;
• Lombardia Informatica S.p.A.;
• Namirial S.p.A.;
• Net Studio S.p.A.;
• Poste Italiane S.p.A.;
• Regione Toscana;
• Register.it S.p.A.;
• Sielte S.p.A.;
• Sistemi Informativi S.r.l.;
• Sogei S.p.A.;
• Team per la Trasformazione Digitale;
• TI Trust Technologies S.r.l.

I soggetti destinatari delle presenti linee guida sono: i Gestori dell’identità digitale e i Fornitori di servizi di cui al DPCM 24 ottobre 2014, “Definizione delle caratteristiche del sistema pubblico per la gestione dell’identità digitale di cittadini e imprese (SPID), nonché dei tempi e delle modalità di adozione del sistema SPID da parte delle pubbliche amministrazioni e delle imprese”.

Le presenti Linee Guida entreranno in vigore 6 mesi dopo la loro adozione da parte dell’Agenzia per l’Italia Digitale.

Riferimenti Normativi¶

• [Reg. UE n.910/2014] Regolamento (UE) n. 910/2014 del 23 luglio 2014 in materia di identificazione elettronica e servizi fiduciari per le transazioni elettroniche nel mercato interno e che abroga la direttiva 1999/93/CE;
• [D.Lgs. 82/2005] Decreto legislativo 7 marzo 2005, n. 82 e s.m.i. recante “Codice dell’amministrazione digitale”;
• [DPCM 24 ottobre 2014] recante “Definizione delle caratteristiche del sistema pubblico per la gestione dell’identità digitale di cittadini e imprese (SPID), nonché dei tempi e delle modalità di adozione del sistema SPID da parte delle pubbliche amministrazioni e delle imprese.”;
• [Regolamento recante le regole tecniche] (articolo 4, comma 2, DPCM 24 ottobre 2014) e s.m.i.;
• [Regolamento recante le modalità attuative per la realizzazione dello SPID] (articolo 4, comma 2, DPCM 24 ottobre 2014) e s.m.i.

Standard di riferimento¶

SPID OpenID Connect è basato sul profilo iGov (openid-gov-profile) di OpenID Connect, International Government Assurance Profile (iGov) for OpenID Connect 1.0, con la seguente personalizzazione:

• paragrafo 4,2 di openid-igov-openid-connect-1_0: Scope: viene utilizzato solo lo scope «openid» e non «bio», «profile» e «doc» come suggerito dal profilo iGov;
• paragrafo 3,7 e 2,5 di openid-igov-openid-connect-1_0: I metadata degli attori sono distribuiti secondo le modalità definite dall’Agenzia per l’Italia Digitale.

Riferimenti

Termini e definizioni¶

Essendo le funzionalità simili, ritroviamo gli stessi concetti di SAML 2.0 anche in OpenID Connect:

Ai fini delle presenti Linee Guida, per OpenID Provider (OP) e Relying Party (RP) si intendono rispettivamente i Gestori dell’identità digitale (Identity Provider - IdP) e i Fornitori di servizi (Service Provider - SP) di cui al DPCM 24 ottobre 2014, “Definizione delle caratteristiche del sistema pubblico per la gestione dell’identità digitale di cittadini e imprese (SPID), nonché dei tempi e delle modalità di adozione del sistema SPID da parte delle pubbliche amministrazioni e delle imprese.”

OpenID Provider (OP) Metadata¶

Il formato del metadata deriva da quanto specificato nel documento «OpenID Connect Discovery 1.0», del quale costituisce un sottoinsieme con alcuni campi in aggiunta.

Esempio:

{
  "issuer": "https://op.fornitore_identita.it",
  "authorization_endpoint": "https://op.fornitore_identita.it/auth",
  "token_endpoint": "https://op.fornitore_identita.it/token",
  "userinfo_endpoint": "https://op.fornitore_identita.it/userinfo",
  "introspection_endpoint": "https://op.fornitore_identita.it/introspect",
  "revocation_endpoint": "https://op.fornitore_identita.it/revoke",
  "end_session_endpoint": "https://op.fornitore_identita.it/logout",
  "jwks_uri": "https://registry.spid.gov.it/...",
  "id_token_encryption_alg_values_supported": [
      "..."
  ],
  "userinfo_signing_alg_values_supported": [
      "..."
  ],
  "request_object_encryption_enc_values_supported": [
      "..."
  ],
  "token_endpoint_auth_methods_supported": ["private_key_jwt"],
  "userinfo_encryption_alg_values_supported": [
      "..."
  ],
  "id_token_encryption_enc_values_supported": [
      "..."
  ],
  "id_token_signing_alg_values_supported": [
      "..."
  ],
  "request_object_encryption_alg_values_supported": [
      "..."
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
      "..."
  ],
  "request_object_signing_alg_values_supported": [
      "..."
  ],
  "userinfo_encryption_enc_values_supported": [
      "..."
  ],
  "claims_supported":[
    "https://attributes.spid.gov.it/spidCode",
    "https://attributes.spid.gov.it/name",
    "https://attributes.spid.gov.it/familyName",
    "https://attributes.spid.gov.it/placeOfBirth",
    "https://attributes.spid.gov.it/countyOfBirth",
    "https://attributes.spid.gov.it/dateOfBirth",
    "https://attributes.spid.gov.it/gender",
    "https://attributes.spid.gov.it/companyName",
    "https://attributes.spid.gov.it/registeredOffice",
    "https://attributes.spid.gov.it/fiscalNumber",
    "https://attributes.spid.gov.it/ivaCode",
    "https://attributes.spid.gov.it/idCard",
    "https://attributes.spid.gov.it/mobilePhone",
    "https://attributes.spid.gov.it/email",
    "https://attributes.spid.gov.it/address",
    "https://attributes.spid.gov.it/expirationDate",
    "https://attributes.spid.gov.it/digitalAddress"
  ],
  "acr_values_supported":[
    "https://www.spid.gov.it/SpidL1",
    "https://www.spid.gov.it/SpidL2",
    "https://www.spid.gov.it/SpidL3
  ],
  "request_parameter_supported": true,
  "subject_types_supported":["public"],
  "op_name": "Agenzia per l'Italia Digitale",
  "op_name#en": "Agency for Digital Italy",
  "op_url": "https://www.agid.gov.it",
  "op_url#en": "https://www.agid.gov.it/en"
}

Esempio di risorsa jwks_uri:

{
  "keys": [
    {
     "kty": "EC",
     "kid": "sig-ec256-0",
     "use": "sig",
     "crv": "P-256",
     "x": "2jM2df3IjB9VYQ0yz373-6EEot_1TBuTRaRYafMi5K0",
     "y": "h6Zlz6XReK0L-iu4ZgxlozJEXgTGUFuuDl7o8b_8JnM"
    },
    {
     "kty": "EC",
     "kid": "enc-ec256-0",
     "use": "enc",
     "crv": "P-256",
     "x": "QI31cvWP4GwnWIi-Z0IYHauQ4nPCk8Vf1BHoPazGqEc",
     "y": "DBwf8t9-abpXGtTDlZ8njjxAb33kOMrOqiGsd9oRxr0"
    }
   ]
}

Riferimenti

Client Metadata (Relying Party Metadata)¶

Il formato del metadata deriva da quanto specificato nel documento «OpenID Connect Discovery 1.0», del quale costituisce un sottoinsieme con alcuni campi in aggiunta.

Esempio:

{
  "client_id": "https://rp.spid.agid.gov.it",
  "redirect_uris": [
    "https://rp.spid.agid.gov.it/callback1/",
    "https://rp.spid.agid.gov.it/callback2/"
  ],
  "jwks_uri": "https://registry.spid.gov.it/...",
  "jwks": {
    "keys": [
     {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "kid": "e27671d73a2605ccd454413c4c94e25b3f66cdea",
      "n": "vmyoDT6ND_YJa1ItdvULuTJr2pw4MvN3Z5kmSiJBm9glVoakcDEBGF4b5c7WDh2P...",
      "e": "ABAB"
     }
    ]
  },
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"],
  "client_name": "Agenzia per l'Italia Digitale",
  "client_name#en": "Agency for Digital Italy"
}

Riferimenti

Applicazioni per dispositivi mobili¶

Nel caso di applicazioni mobili rimane il requisito di seguire l’Authorization Code Flow descritto sopra.

In tale contesto, nel diagramma di cui al paragrafo precedente, l’elemento identificato come Relying Party sta ad identificare l’insieme della applicazione residente sul dispositivo mobile e del suo eventuale backend.

Le richieste al Token Endpoint e allo UserInfo Endpoint possono pertanto essere inviate sia dall’applicazione sia dal suo backend; lo scambio di informazioni tra l’applicazione mobile e il suo eventuale backend non sono normate dal presente documento, ferma restando la raccomandazione di prevedere meccanismi di trasmissione e archiviazione sicuri che impediscano a terze parti di venire in possesso dell’Access Token.

Per inviare la Authentication Request all’OP è possibile usare il browser o una webview, purché protetta con i meccanismi più sicuri messi a disposizione dai sistemi operativi al fine di ottenere il massimo isolamento dall’applicazione chiamante. A tal fine si consiglia l’uso della libreria AppAuth e si rinvia alle indicazioni contenute nelle Linee Guida User Experience SPID.

Si rimanda a RFC8252 per ulteriori specifiche tecniche e raccomandazioni di sicurezza da applicarsi in caso di applicazioni mobili.

Riferimenti

Claims¶

Il parametro claims definisce gli attributi e il livello SPID richiesti. all’interno dell’elemento «userinfo» si elencano gli attributi, da richiedere come chiavi di oggetti JSON, i cui valori devono essere null. Gli attributi elencati sotto «userinfo» sono disponibili al momento della chiamata allo UserInfo Endpoint.

{
 "userinfo":
  {
   "https://attributes.spid.gov.it/familyName":
    {
     "essential": true
    }
  },
}

Se il Relying Party è privato, gli OpenID Provider devono controllare che gli attributi richiesti rientrino tra quelli che essi, in base alla convenzione, possono utilizzare.

Riferimenti:

Generazione del code_challenge per PKCE¶

PKCE (Proof Key for Code Exchange, RFC7636) è un’estensione del protocollo OAuth 2.0 finalizzata ad evitare un potenziale attacco attuato con l’intercettazione dell’authorization code, soprattutto nel caso di applicazioni per dispositivi mobili. Consiste nella generazione di un codice (code verifier) e del suo hash (code challenge). Il code challenge viene inviato all’OP nella richiesta di autenticazione.

Quando il client contatta il Token Endpoint al termine del flusso di autenticazione, invia il code verifier originariamente creato, in modo che l’OP possa confrontare che il suo hash corrisponda con quello acquisito nella richiesta di autenticazione.

Il code verifier deve avere una lunghezza compresa tra 43 e 128 caratteri e deve essere generato con un algoritmo crittografico ad alta entropia.

Il code challenge deve essere generato con algoritmo SHA256.

Riferimenti:

Response¶

Se l’autenticazione è avvenuta con successo, l’OpenID Provider (OP) Authorization server, reindizza l’utente con i seguenti parametri:

Errori¶

In caso di errore, l’OP visualizza i messaggi definiti dalle Linee Guida UX SPID. Nei casi in cui tali linee guida prescrivono un redirect dell’utente verso il RP, l’OP effettua il redirect verso l’URL indicata nel parametro redirect_uri della richiesta (solo se valido, ovvero presente nel client metadata), con i seguenti parametri.

Esempio:

Di seguito i codici di errore:

Riferimenti:

Request¶

Esempio di richiesta con authorization code (caso 1):

Esempio di richiesta con refresh token (caso 2):

Response¶

Dopo avere ricevuto e validato la Token request dal client, il Token endpoint dell’OpenID Provider (OP) restituisce una response che include ID Token e Access Token e un eventuale Refresh Token, in formato JWT e firmati secondo le modalità definite dall’Agenzia per l’Italia Digitale.

Access Token e ID Token devono essere formati secondo le indicazioni dello standard “International Government Assurance Profile (iGov) for OAuth 2.0 - Draft 03, paragrafo 3.2.1, “JWT Bearer Tokens”.

{
 "access_token": "dC34Pf6kdG...",
 "token_type": "Bearer",
 "refresh_token": "wJ848BcyLP...",
 "expires_in": 1800,
 "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY..."
}

ID Token¶

L’ID Token è un JSON Web Token (JWT) che contiene informazioni sull’utente che ha eseguito l’autenticazione. I Client devono eseguire la validazione dell’ID Token.

Esempio di ID Token:

{
 "iss": "https://rp.spid.agid.gov.it/",
 "sub": "OP-1234567890",
 "aud": "https://op.spid.agid.gov.it/auth",
 "acr": "https://www.spid.gov.it/SpidL2",
 "at_hash": "qiyh4XPJGsOZ2MEAyLkfWqeQ",
 "iat": 1519032969,
 "nbf": 1519032969,
 "exp": 1519033149,
 "jti": "nw4J0zMwRk4kRbQ53G7z",
 "nonce": "MBzGqyf9QytD28eupyWhSqMj78WNqpc2"
}

Riferimenti:

Errori¶

In caso di errore, l’OP restituisce un codice HTTP 401 con un JSON nel body avente gli elementi di seguito indicati.

Esempio:

{
  "error": "invalid_client",
  "error_description: "client_id non riconosciuto."
}

Di seguito i codici di errore:

Riferimenti:

Response¶

La response dello UserInfo Endpoint deve essere firmata e cifrata secondo le modalità definite dall’Agenzia per l’Italia Digitale. Lo UserInfo Endpoint restituisce i claim autorizzati nella Authentication Request.

Esempio:

{
  "iss": "https://op.fornitore_identita.it",
  "aud": "https://rp.fornitore_servizio.it",
  "iat": 1519032969,
  "nbf": 1519032969,
  "exp": 1519033149,
  "sub": "OP-1234567890",
  "https://attributes.spid.gov.it/name": "Mario",
  "https://attributes.spid.gov.it/familyName": "Rossi",
  "https://attributes.spid.gov.it/fiscalNumber": "MROXXXXXXXXXXXXX"
}

In caso di errore di autenticazione, lo UserInfo Endpoint restituisce un errore “HTTP 401”.

Request¶

La richiesta all’Introspection Endpoint consiste nell’invio del token su cui si vogliono ottenere informazioni unitamente ad una Client Assertion che consente di identificare il RP che esegue la richiesta.

Esempio:

Response¶

L’Introspection Endpoint risponde con un oggetto JSON definito come segue.

Esempio:

{
  "active": true,
  "scope": "foo bar",
  "exp": 1519033149,
  "sub": "OP-1234567890",
  "client_id": "https://rp.agid.gov.it/"
}

Errori¶

In caso di errore, l’OP restituisce un codice HTTP 401 con un JSON nel body avente gli elementi di seguito indicati.

Esempio:

{
 "error": "invalid_client",
 "error_description: "client_id non riconosciuto."
}

Di seguito i codici di errore:

Riferimenti:

Request¶

La richiesta al Revocation Endpoint consiste nell’invio del token che si vuole revocare unitamente ad una Client Assertion che consente di identificare il RP che esegue la richiesta.

Esempio:

Response¶

Il Revocation Endpoint risponde con un codice HTTP 200, anche nel caso in cui il token indicato non esista o sia già stato revocato (in modo da non rilasciare informazioni).

Ambiti e limiti di utilizzo¶

1. Al primo avvio dell’applicazione l’Utente deve essere informato della possibilità di utilizzare la sessione lunga revocabile, per mantenere un’autenticazione di SPID di livello 1 che consenta all’applicazione di ricevere unicamente notifiche o call to action da parte dello SP, anche quando l’Utente “non sia presente”;
2. Le applicazioni mobili che fanno uso di sessioni lunghe revocabili sono tenute a richiedere all’utente, ad ogni avvio o attivazione, un PIN locale oppure un fattore biometrico.
3. In fase di installazione o di prima configurazione, l’applicazione chiede all’utente di registrare il fattore di autenticazione da utilizzare per ogni avvio successivo al primo.
4. Quando l’Utente avvia nuovamente l’applicazione, questa deve richiedere all’Utente il fattore di autenticazione scelto in fase di installazione o di prima configurazione e consentire l’accesso alle funzioni del RP fruibili con il Livello 1 di SPID.
5. Nel caso in cui sia necessario accedere all’applicazione con un livello superiore a SPID di Livello 1, occorre effettuare una nuova autenticazione SPID in base al livello richiesto.

Request¶

Per poter utilizzare le sessioni lunghe revocabili, l’RP include nella Authentication Request:

• lo scope “offline_access”, al fine di ottenere un refresh token utilizzabile dietro espressa consenso dell’utente;
• il parametro “acr_values” contenente una delle seguenti opzioni:
  • il livello SPID 1;
  • il livello SPID 2 + il livello SPID 1.
  • il livello SPID 3 + il livello SPID 1.

Refresh Token¶

Se nella Request è incluso lo scope “offline_access”, il Token Endpoint dell’OP restituisce oltre all’access token anche un refresh token.

Introspection¶

Ad ogni successivo avvio della propria applicazione, il RP può inviare una richiesta all’Introspection Endpoint per verificare che l’access token in suo possesso sia ancora valido.

In caso negativo, deve inviare una richiesta al Token Endpoint con il refresh token in suo possesso, per ottenere un nuovo access token.

Nel caso in cui il Token Endpoint rifiuti la concessione di un nuovo access token, l’utente dovrà effettuare un nuovo login SPID.

Esempio¶

Un RP fornisce servizi per i quali è necessaria un’autenticazione di liv 1 o di livello 2.

Il RP, per consentire l’accesso, effettua una richiesta di autenticazione, all’OP con acr_values=https://www.spid.gov.it/SpidL2 https://www.spid.gov.it/SpidL1

L’“authorization server” autentica l’utente, sulla base del Livello SPID richiesto dal RP (Livello 1 o Livello 2 o Livello 3), c.d. “autenticazione originaria”, e rilascia un unico “access_token” sia per il Livello SPID 1 sia per il Livello SPID richiesto dal SP, con una scadenza di 15 minuti, e rilascia un “refresh_token” per il solo livello SPID 1 con scadenza 30 giorni.

L’OP consente l’accesso sia al livello «SPID1» sia al livello «SPID2» per 15 mins mediante l’“access_token”.

Quando l’“access_token” scade, l’OP non consente l’accesso con tale l’access token e il RP deve ottenere un nuovo «access_token» tramite nuova autenticazione oppure tramite una «richiesta di refresh».

Il RP effettua una “richiesta di refresh” con il refresh_token.

Il “token endpoint” verifica la validità del refresh_token, e se nella richiesta di autenticazione originaria era presente nell’“acr_values” il livello “SPID1”, rilascia un nuovo ID Token valido esclusivamente per il livello «SPID1» con scadenza a 30 giorni dall’autenticazione originaria.

Esempio (chiamata HTTP):

Esempio (contenuto del JWT):

{
   client_id=https%3A%2F%2Frp.spid.agid.gov.it,
   code_challenge=qWJlMe0xdbXrKxTm72EpH659bUxAxw80,
   code_challenge_method=S256,
   nonce=MBzGqyf9QytD28eupyWhSqMj78WNqpc2
   prompt=login,
   redirect_uri=https%3A%2F%2Frp.spid.agid.gov.it%2Fcallback1%2F,
   response_type=code,
   scope=openid offline_access,
   acr_values=https://www.spid.gov.it/SpidL2 https://www.spid.gov.it/SpidL1,
   claims={
       "userinfo":{
           "https://attributes.spid.gov.it/name": null,
           "https://attributes.spid.gov.it/familyName": null
       },
    }&
   state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd
}

Esempio Refresh (chiamata HTTP):

Nel caso in cui il Token Endpoint rifiuti la concessione di un nuovo ID token e access token, l’utente dovrà effettuare un nuovo login SPID.

Nel caso in cui sia necessario accedere all’applicazione con un livello superiore a SPID di Livello 1, occorre effettuare una nuova autenticazione SPID in base al livello richiesto.

Se la Refresh Request è valida, l’OpenID Connect Provider restituisce un ID Token con i seguenti parametri:

Il refresh token ottenuto con la richiesta di autenticazione ha una validità massima di 30 giorni, entro i quali potrà essere utilizzato un numero illimitato di volte. Allo scadere dei 30 giorni non potrà più essere utilizzato e sarà necessario rieseguire l’autenticazione completa.

Riferimenti:

Gestione delle sessioni¶

Al fine di poter gestire le sessioni lunghe revocabili e poter rilasciare un refresh token per il Livello 1 di SPID anche a seguito di un’autenticazione di Livello 2 o 3 di SPID, è ammessa l’instaurazione, per ogni livello di SPID, di una sessione di autenticazione associata ad un determinato utente titolare di identità digitale, mantenuta dal gestore dell’identità digitale.

Gli OP devono includere all’interno della “Pagina di gestione dell’identità SPID”, descritta nelle Linee Guida UX SPID, un’interfaccia per visualizzare le sessioni lunghe revocabili attive, dove l’utente possa revocarle singolarmente o in massa.

In caso di modifica della password richiesta dall’utente, l’OP deve prevedere la possibilità di revocare tutte le sessioni lunghe attive.