REGIONE TOSCANA REGIONE TOSCANA SU STANDARD OAUTH2 DOCUMENTO TECNICO - LINEE GUIDA PER L'INTEGRAZIONE DI APPLICAZIONI - Regione ...
←
→
Trascrizione del contenuto della pagina
Se il tuo browser non visualizza correttamente la pagina, ti preghiamo di leggere il contenuto della pagina quaggiù
REGIONE TOSCANA
LINEE GUIDA PER L'INTEGRAZIONE DI APPLICAZIONI
NELLA INFRASTRUTTURA DI AUTENTICAZIONE DI
REGIONE TOSCANA SU STANDARD OAUTH2
DOCUMENTO TECNICO
LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
Controllo del Documento
Numero di Versione 1.10
Data del Documento 05/08/2021
Autori Redatto da C.Simonelli (TAI), G.Graziano (TAI), A.Poli
(Link.it)
Revisionato da F.Fornasari (TAI)
Approvato da
Stato Proposto per approvazione
Storia del documento
Versione Data Descrizione
1.0 01/06/2018 Prima Versione
1.1 24/07/2018 Ristrutturazione di alcune spiegazioni e casi
d’uso
1.2 17/09/2018 Integrazione Api Gateway
1.3 02/10/2018 Inserite ulteriori precisazioni
1.4 18/10/2018 Aggiornati Scope
1.5 28/02/2019 Rimosso supporto implicit grant
1.6 08/07/2020 Rimossi riferimenti extra OAuth2
1.7 17/11/2020 Aggiunge informazioni su AuthRefId
1.8 17/11/2020 Reintroduzione paragrafo API Gateway del CART
1.9 05/07/2021 Aggiunte specifiche Logout
1.10 05/08/2021 Integrazione Eidas
1.11 11/10/2021 Revisione per introduzione eIDAS e Spid
Professionale
1.12 07/12/2021 Introdotto Allegato A
1.13 20/12/2021 Correzione refusi
2LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
Indice del documento
1 Introduzione ................................................................................... 5
1.1 Standard di riferimento ......................................................................................................................... 7
1.2 Casi d’uso ............................................................................................................................................... 7
2 Client ............................................................................................. 7
3 Resource Server .............................................................................. 8
3.1 Erogazione dei servizi mediante API Gateway del CART ....................................................................... 9
3.2 Erogazione diretta dei servizi da parte del Resource Server ............................................................... 10
3.2.1 Verifica Access Token attraverso Introspection 11
3.2.2 Verifica Access Token attraverso decodifica JWT 12
3.2.3 Formato Access Token JWT e risposta Introspection. 12
4 Authorization Server .......................................................................16
5 Monitoraggio delle applicazioni e logging ...........................................19
5.1 5.1 Utilizzo AuthRefId .......................................................................................................................... 20
6 Logout ..........................................................................................20
1. Allegato A - Authentication Type.......................................................22
a. Introduzione ........................................................................................................................................ 22
b. Tipologia identità digitali supportate per tipologia di autenticazione ................................................ 23
c. Differenze di base tra gli Authentication Types .................................................................................. 23
d. Schema attributi per Authentication Types ........................................................................................ 25
3LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
Indice delle tabelle
Tabella 1: Endpoint Token Introspection 11
Tabella 2: Endpoint certificato Json Web Key 12
Tabella 3: Attributi Access Token 13
Tabella 4: Esempio di risposta - token introspection 14
Tabella 5: Attributi Opzionali Access Token e Introspection 15
Tabella 6: Esempio di risposta - token introspection 15
Tabella 7: Authorization request con scope 16
Tabella 8: Endpoint UserInfo 16
Tabella 9: Attributi UserInfo 17
Tabella 10: UserInfo response 18
Tabella 11: Schema attributi per Authentication Type 27
4LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
1 Introduzione
L’obiettivo del documento è fornire le linee guida che consentano, a servizi http oppure
applicazioni mobile, di effettuare l’autenticazione attraverso gli standard OAuth2 e
OpenId Connect.
Oauth2 definisce quattro ruoli:
1) Resource Owner (il soggetto fisico o giuridico che autorizza il servizio o l’app
ad accedere ai propri dati)
2) Client sono le applicazioni (Web, Mobile, Desktop) che desiderano accedere alle
informazioni dell’utente.
3) Resource Server sono servizi http che possono essere utilizzati dai client una
volta ottenuto il token di accesso.
4) Authorization Server è il componente di infrastruttura che si occupa di
autenticare il soggetto e rilascia access token ai client autorizzati.
La documentazione riguarda sia gli sviluppatori di applicazioni Client che gli sviluppatori
dei Resource Server.
In funzione degli scenari di deploy dei singoli progetti saranno possibili varie modalità
di utilizzo delle specifiche di cui sopra. La figura che segue mostra uno schema di
dispiegamento in un tipico scenario applicativo basato su OAuth2.
Figura 1 - Tipico Scenario Oauth2
L'applicazione Client interagisce con l'Authorization Server per ottenere il Token
necessario per l'accesso ai servizi erogati dal Resource Provider. In questa fase, in
funzione delle caratteristiche dell’applicazione client potrà essere coinvolto l’utente
5LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
finale, sia per la sua autenticazione, che per l’eventuale espressione del consenso
all’accesso dei propri dati da parte delle applicazioni coinvolte. Il Token ottenuto
dall’applicazione Client sarà quindi trasmesso dal Client al Resource Provider nelle
successive richieste applicative. Il Resource Provider potrà quindi provvedere alla
validazione del token ed all’autorizzazione della richiesta sulla base delle informazioni
contenute nel token, prima di consentire l’accesso del Client alle risorse richieste.
Una possibile variante di questo scenario di dispiegamento prevede la presenza dell’API
Gateway a protezione del Resource Server, come mostrato nella figura seguente.
Figura 2 - Scenario OAuth2 con API Gateway
Il comportamento delle applicazioni in gioco è molto simile al caso precedente, tranne
per quanto riguarda la possibilità di delegare all’API Gateway una parte delle funzioni di
validazione del token e di autorizzazione delle richieste in arrivo. Tutte le informazioni
necessarie per la corretta operatività o per attivare meccanismi di autorizzazione più
specifici saranno comunque trasmesse al Resource Provider, ma solo dopo aver
effettuato opportune verifiche sulla correttezza della richiesta ricevuta.
Nel seguito del documento saranno descritte le modalità di integrazione previste per le
applicazioni di tipo Client e di tipo Resource Provider.
6LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
1.1 Standard di riferimento
Le modalità di integrazione descritte nel seguito fanno riferimento agli
standard OAuth2, OIDC 1.0 e JWT, ed in particolare ai documenti di specifica
elencati nella tabella seguente, di cui si assume la conoscenza da parte del
lettore.
Specifica Riferimento
OAuth 2.0 Authorization https://tools.ietf.org/html/rfc6749
Framework
OpenID Connect 1.0 Core (OIDC) http://openid.net/specs/openid-connect-core-1_0.htm
OAuth 2.0 Authorization https://tools.ietf.org/html/rfc6750
Framework: Bearer Token Usage
OAuth 2.0 Token Introspection https://tools.ietf.org/html/rfc7662
JSON Web Token (JWT) https://tools.ietf.org/html/rfc7519
https://www.agid.gov.it/sites/default/files/repository_files/c
Autenticazione Spid ircolari/regolamento_modalita_attuative_spid_2.0.pdf
1.2 Casi d’uso
Per i casi di uso e le modalità di integrazione si rimanda al manuale operativo
apposito:
CASI D’USO INTEGRAZIONE DI APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU STANDARD OAUTH2
2 Client
Il sistema autorizzativo di Regione Toscana mette a disposizione entrambe le
tipologie di client definiti nello standard Oauth2
(https://tools.ietf.org/html/rfc6749#section-2.1):
● Confidential – Client in grado di mantenere in modo sicuro le credenziali
rilasciate, come applicazioni web. In tal caso verranno rilasciate credenziali
clientId e secret.
● Public – Client che per loro natura non sono in grado di mantenere in modo
sicuro le credenziali, come app mobile e client javascript. In questo caso verrà
rilasciato il solo clientId
7LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
L’autenticazione dei client dovrà avvenire utilizzando clientId e secret in accordo
a quanto indicato nella sezione “Client Password” del RFC6749
(https://tools.ietf.org/html/rfc6749#section-2.3.1).
Le credenziali client verranno rilasciate a seguito di una richiesta che contenga
almeno le seguenti informazioni:
1) Nome dell’applicazione Client
2) Access type: Confidential o Public.
3) Grant Type: Authorization Grant o Client Credential Grant
Solo per Grant Type Authorization:
4) Redirect URL dove inviare il code per il recupero dell’access token.
5) Livello di autenticazione utente minimo richiesto dal Client (livello 2 o 3 Spid,
CNS). Default: 4
È possibile inoltre richiedere i seguenti controlli attivabili in fase di rilascio del token al
Client da parte dell’Authorization Server:
6) Solo per la tipologia Authorization Grant è possibile specificare i ruoli richiesti agli
utenti coinvolti.
7) Lista eventuali Resource Server (Audience) a cui il token è destinato. Default:
ammesso solo l’utilizzo della funzionalità di UserInfo (vedi Authorization Server,
UserInfo EndPoint).
3 Resource Server
Resource server è il termine OAuth2 utilizzato per definire i servizi http che
possono essere invocati utilizzando un token di accesso (vedi
https://tools.ietf.org/html/rfc7662).
Per integrare un servizio all’interno dell’infrastruttura di Regione Toscana
dovranno essere fornite le seguenti informazioni:
1) Nome dell’applicazione
2) Modalità di erogazione dei servizi: diretta. In funzione della tipologia di deploy
degli applicativi, che sarà concordata per ogni progetto con i referenti di Regione
Toscana, i Resource Server potranno operare in una delle due modalità.
3) Solo per grant type Authorization è possibile indicare il livello di autenticazione
minimo richiesto. Se non configurato si intende il livello più elevato (CNS).
È possibile inoltre attivare i seguenti ulteriori controlli attivabili in fase di rilascio del
token al Client da parte dell’Authorization Server:
8LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
4) Elenco degli scope gestiti dal Resource Server (ad esempio, LetturaDatiSanitari).
Tale informazione sarà utilizzata in fase di rilascio del token per verificare la
coerenza degli scope richiesti dai Client. Resta comunque a carico del Resource
Server consentire l’accesso alla funzionalità desiderata solo se nel token sono
presenti gli scope necessari.
Default: se non richiesto ne viene generato uno per il Resource Server che sarà
comunicato dai gestori dell’infrastruttura.
3.1 Erogazione dei servizi mediante API Gateway del CART
In questa modalità, le richieste in arrivo dai Client sono mediate dall’API Gateway del
CART, che si occuperà di:
1. validare l’access token in arrivo; nel caso questo non sia valido la richiesta sarà
scartata immediatamente senza nessuna interazione con il Resource Server;
2. estrarre le informazioni contenute nel token al fine di tracciamento della richiesta;
3. se richiesto, le seguenti informazioni contenute nel token potranno essere
utilizzate per l’autorizzazione della richiesta:
● Elenco di Ruoli RT dell’Utente: la richiesta sarà autorizzata solo se l’utente
possegga uno solo o tutti i ruoli indicati.
● Elenco di Scope: la richiesta sarà autorizzata solo se l’utente possegga uno
solo o tutti gli ‘scope’ indicati.
● Elenco di Audience: nel token deve essere presente il claim ‘aud’ e deve
corrispondere ad uno dei valori indicati
● Elenco di Client: nel token deve essere presente il claim ‘azp’ e deve
corrispondere ad uno dei valori indicati
● Livello di Autenticazione: la richiesta sarà autorizzata solo se l’autenticazione
dell’utente sia avvenuta al livello indicato
Politiche più complesse, non realizzabili tramite le regole di cui sopra, possono
essere espresse tramite policy XACML. In tal caso sarà disponibile il necessario
supporto per la realizzazione delle policy.
I criteri di autorizzazione possono essere eventualmente differenziati per le
diverse risorse invocate (HttpMethod + Path).
4. Infine, se le fasi precedenti sono state superate con successo, la richiesta sarà
propagata al Resource Server, includendo sia l’Access Token originale
(decodificabile come specificato nella successiva sezione 3.2- Erogazione diretta
dei servizi da parte del Resource Server) che le informazioni contenute nel token
9LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
decodificate all’interno di appositi header HTTP della richiesta applicativa, come
specificato nella tabella seguente.
Header Name Header Value
X-CART-id identificativo unico di transazione generato dalla PdA del CART
X-CART- timestamp gestione transazione da parte della PdA, espresso come
pdaTime secondi trascorsi dal 1 Gennaio 1970.
identificativo dell’applicativo che ha effettuato la richiesta applicativa.
X-CART-clientId L’informazione è presente solo se l’autenticazione del client è abilitata
sull’API Gateway per questo tipo di richiesta.
X-CART-
fiscalNumber
X-CART-name
Informazioni estratte dall’access token, se presenti. Il formato è lo
X-CART-
stesso descritto nella sezione Verifica Access Token attraverso
familyName
decodifica JWT.
X-CART-email
X-CART-
ivaCode
X-CART-
identificativo dell’applicazione client che ha generato il token Oauth.
oauthClientId
elenco degli scope, separati con una virgola, eventualmente presenti
X-CART-scope
nel token Oauth.
elenco dei ruoli dell’utente, separati da virgola.
X-CART-roles In questa modalità vengono forniti soltanto i ruoli di un utente e non
i relativi attributi.
3.2 Erogazione diretta dei servizi da parte del Resource Server
Nel caso in cui il Resource Server sia esposto direttamente, dovrà necessariamente
effettuare la validazione dell'access token che riceverà secondo la modalità
“Authorization Request Header Field” prevista dalla specifica “RFC 6750 - Bearer Token
Usage” (https://tools.ietf.org/html/rfc6750#section-2.1).
Successivamente il resource server, al fine di limitare l’accesso alle proprie API, può
estrarre le informazioni disponibili nell’access token. Per farlo, può utilizzare una delle
due modalità seguenti:
10LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
1. Attraverso l’invocazione del servizio Token Introspection
2. Mediante decodifica access token JWT (Json Web Token)
3.2.1 Verifica Access Token attraverso Introspection
Per ogni Resource Server viene generata una credenziale client di tipo “confidential” che
può essere usata dal gestore del resource server per accedere alla funzionalità di token
introspection.
L’endpoint Introspect è messo a disposizione dall’infrastruttura di Regione Toscana ed
è realizzato secondo lo standard RFC7662 (https://tools.ietf.org/html/rfc7662)
In figura è mostrato il diagramma di sequenza di utilizzo del servizio introspect:
Figura 3: Invocazione Servizio Introspect
Di seguito la descrizione delle operazioni nel caso di utilizzo del servizio introspection:
1) Il Resource Server riceve un’invocazione con l’access token presente nella
richiesta
2) Il Resource Server effettua un’invocazione all’endpoint Introspect con l’access
token ricevuto allo step precedente e le credenziali
3) L’authorization Server risponde con le informazioni relative alla validità del token
4) Il Resource Server verifica la validità del token (effettua caching per richieste
successive) e verifica che lo scope sia valido per l’API invocata ed eventualmente
esegue il metodo richiesto e restituisce il risultato.
L’endpoint per decodificare l’access token è il seguente:
Specifica EndPoint Introspection
11LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
OAuth 2.0 Token Introspection Ambiente di Produzione
https://accessosicuro.rete.toscana.it/auth/realms/arp
https://tools.ietf.org/html/rfc7 a/protocol/openid-connect/token/introspect
662
Tabella 1: Endpoint Token Introspection
La richiesta sarà effettuata tramite basic authentication, utilizzando le credenziali
(client_id e client_secret) ottenute in fase di registrazione. Il formato della risposta è
descritto nel prossimo paragrafo.
3.2.2 Verifica Access Token attraverso decodifica JWT
L’access Token che il resource server riceve è nel formato JWT (JSON Web Token,
RFC7519 https://tools.ietf.org/html/rfc7519) che contiene praticamente le stesse
informazioni che si otterrebbero invocando il servizio introspect.
Attraverso la decodifica dell’access token non è quindi necessario invocare il servizio
introspect ma è sufficiente validare il token (come durata temporale) e la chiave come
indicato da specifica JSON Web Key.
Specifica EndPoint Certificati
Ambiente di Produzione
JSON Web Key
https://accessosicuro.rete.toscana.it/auth/realms/
https://tools.ietf.org/html/rfc751 arpa/protocol/openid-connect/certs
7
Tabella 2: Endpoint certificato Json Web Key
3.2.3 Formato Access Token JWT e risposta Introspection.
Sia nel caso di utilizzo del servizio token introspection che attraverso la decodifica JWT
dell’access token è possibile recuperare gli attributi che permettono di stabilire validità
del token, metodo di autenticazione utilizzato, ecc. Gli attributi restituiti sono descritti
in Tabella 3.
Nome Descrizione
jti Identificativo unico per il token
exp, nbf Definisce l'intervallo di tempo entro il quale un token è valido. Il
servizio che convalida il token deve verificare che la data corrente
sia compresa nella durata del token. In caso contrario, deve
rifiutare il token.
12LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
iat Archivia l'ora in cui è stato rilasciato il token. Viene spesso
usata per misurare la validità del token.
iss Identifica il servizio token di sicurezza (STS) che
costruisce e restituisce il token.
aud Destinatario previsto per il token. L'applicazione che
riceve il token deve verificare che il valore del gruppo di
destinatari sia corretto e rifiuta tutti i token destinati a un
gruppo di destinatari diverso.
sub Identifica l'entità su cui il token asserisce informazioni, ad
esempio l'utente di un'applicazione. Questo valore non è
modificabile e non può essere riassegnato o riutilizzato, è
quindi possibile usarlo per eseguire controlli di
autorizzazione in modo sicuro.
typ Tipo del token
azp Parte autorizzata – applicazione a cui è stato rilasciato il
token
auth_time Tempo di vita dell’accessToken
session_state Valore univoco che identifica la sessione utente corrente.
acr Indica la modalità di autenticazione del soggetto, invece
del client, nell'attestazione di riferimento alla classe
contesto di autenticazione dell'applicazione. Il valore "0"
indica che l'autenticazione dell'utente finale non soddisfa
i requisiti ISO/IEC 29115.
scope Lista degli scope per i quali l’access token è stato
rilasciato
auth_type Indica lo strumento di autenticazione utilizzato per
l’accesso. Nel caso di accesso con SPID sarà valorizzato
con l’identificativo del Provider utilizzato.
Fare riferimento al file ‘Allegato A’ per maggiori
informazioni.
auth_level Livello di autorizzazione utilizzato per l’accesso,
valorizzato con un numero compreso tra 1 (livello minimo
di autorizzazione, corrispondente a Spid livello 1) e 4
(livello massimo, corrispondente ad accesso con CNS).
13LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
- In caso di accesso con SPID, il livello corrispondente è il
livello di SPID utilizzato (1,2 o 3)
- In caso di accesso con CIE: il livello corrispondente è 3
- In caso di accesso con CNS: il livello corrispondente è 4
authID Auth ID associato al token con cui e’ stato generato
questo evento
spid_code Identificativo associato univocamente alla coppia
che autenticata.
Non è presente in caso di autenticazione con CIE.
Tabella 3: Attributi Access Token
Di seguito è mostrato un esempio di Access Token
{
"jti": "7ddd6563-b3ae-4fd1-98eb-da3299ab0c17",
"exp": 1532339253,
"nbf": 1532338000,
"iat": 1532338953,
"iss": "https://accessosicuro.rete.toscana.it/auth/realms/arpa",
"aud": "clientID",
"sub": "adac8715-ae9a-45f8-9399-5ac3a747f828",
"typ": "Bearer",
"azp": " clientID ",
"auth_time": 1532338694,
"session_state": "53904b71-3178-4b0d-b83a-ad7005893562",
"acr": "0",
"scope": "read_contact”,
"auth_type": "CNS",
"auth_level": "4"
}
Tabella 4: Esempio di risposta - token introspection
È possibile ottenere attributi utente aggiuntivi se il relativo scope è stato richiesto, dal
client, in fase di autorizzazione (vedi https://openid.net/specs/openid-connect-core-
1_0.html#AuthRequest). L’elenco degli scope qualificanti è descritto in Tabella 5.
Nome Scop Descrizione
e
14LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
name profile Nome dell’utente. Presente in caso di persona
fisica
family_name profile Cognome dell’utente. Presente in caso di
persona fisica
preferred_usernam profile Codice fiscale dell’utente in caso di persona
e fisica oppure partita iva nel caso di persona
giuridica
fiscal_number profile Codice fiscale dell’utente. Presente in caso di
persona fisica. Per il formato si faccia
riferimento alla codifica
dell’attributo CF per i certificati, proposta
nell’ambito del Draft ETSI EN 319 412-1, che
nel
caso specifico prevede la seguente
composizione:
TINIT-
Questo campo non appare quando
l’auth_type è di tipo Eidas
iva_code profile Partita iva dell’utente. Presente in caso di
persona giuridica. Per il formato si faccia
riferimento alla codifica
dell’attributo Partita IVA per i certificati,
proposta
nell’ambito del Draft ETSI EN 319 412-1, che
nel
caso specifico prevede la seguente
composizione:
VATIT-
Tabella 5: Attributi Opzionali Access Token e Introspection
Di seguito è mostrato un esempio di Access Token per il quale viene richiesto lo scope
profile.
{
"jti": "7ddd6563-b3ae-4fd1-98eb-da3299ab0c17",
"exp": 1532339253,
"nbf": 1532338000,
"iat": 1532338953,
15LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
"iss": "https://accessosicuro.rete.toscana.it/auth/realms/arpa",
"aud": "client_id",
"sub": "adac8715-ae9a-45f8-9399-5ac3a747f828",
"typ": "Bearer",
"azp": "client_id",
"auth_time": 1532338694,
"session_state": "53904b71-3178-4b0d-b83a-ad7005893562",
"acr": "0",
"scope": " read_contact profile",
"auth_type": "CNS",
"auth_level": "4",
"name": "MARCO",
"family_name": "ROSSI",
"fiscal_number": " TINIT-marrssg78dsaf7sad8f9",
"preferred_username": "marrssg78dsaf7sad8f9"
}
Tabella 6: Esempio di risposta - token introspection
4 Authorization Server
L’authorization server è parte dell’infrastruttura di Regione Toscana e realizzato secondo
le specifiche Oauth2 e OpenId Connect.
Supporta i seguenti authorization grant:
● Code per Authorization code grant
● Access Token per Client Credential
Di seguito sono descritti gli standard di riferimento e gli endpoint per gli ambienti di
staging e produzione.
Specifica Modalità di EndPoint Authorization Server
ottenimento del Token
OIDC Authorization Code grant: Ambiente di Produzione
1. Authorization:
https://openid.net/specs/ https://accessosicuro.rete.toscana.it/auth/r
openid-connect-core- ealms/arpa/protocol/openid-connect/auth
1_0.html#CodeFlowAuth
2. Token:
https://accessosicuro.rete.toscana.it/auth/r
ealms/arpa/protocol/openid-connect/token
16LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
OAuth2 Client Credentials grant: Ambiente di Produzione
3. Token:
https://tools.ietf.org/htm https://accessosicuro.rete.toscana.it/auth/r
l/rfc6749#section-1.3.4 ealms/arpa/protocol/openid-connect/token
Tabella 7: Authorization request con scope
L’invocazione per ottenere il JSON della userinfo è la seguente:
Specifica EndPoint UserInfo
OIDC User Info EndPoint: Ambiente di Produzione
https://accessosicuro.rete.toscana.it/auth/realms/arp
https://openid.net/specs/open a/protocol/openid-connect/userinfo
id-connect-core-
1_0.html#UserInfo
Tabella 8: Endpoint UserInfo
L’endpoint UserInfo, come da specifiche, accetta l’access Token nell’header
Authorization della richiesta.
La lista degli attributi restituiti dalla UserInfo sono dipendenti dagli scope richiesti dal
client in fase di autorizzazione. Nella Tabella 9 sono mostrati gli attributi restituiti dalla
UserInfo.
Nome Scope Descrizione
name profile Nome dell’utente. Presente in caso di persona
fisica
family_name profile Cognome dell’utente. Presente in caso di
persona fisica
preferred_username profile Codice fiscale dell’utente in caso di persona
fisica oppure partita iva nel caso di persona
giuridica
gender profile Opzionale. Valori ammessi: “F” per sesso
femminile “M” per sesso maschile. Presente
solo in caso di persona fisica
birthdate profile Opzionale. Data di nascita secondo la
specifica xs:date nel format. Presente solo in
caso di persona fisica
birthplace profile Opzionale. Stringa corrispondente al codice
catastale (Codice
Belfiore ) del Comune o della nazione estera
di
17LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
nascita.
(Es. “F205” per la citta di Milano ) . Non
obbligatorio ed eventualmente presente solo
in caso di persona fisica
fiscal_number profile Codice fiscale dell’utente. Presente in caso di
persona fisica. Per il formato si faccia
riferimento alla codifica
dell’attributo CF per i certificati, proposta
nell’ambito del Draft ETSI EN 319 412-1, che
nel
caso specifico prevede la seguente
composizione:
TINIT-
Questo campo non appare quando
l’auth_type è di tipo Eidas
iva_code profile Partita iva dell’utente. Presente in caso di
persona giuridica. Per il formato si faccia
riferimento alla codifica
dell’attributo Partita IVA per i certificati,
proposta
nell’ambito del Draft ETSI EN 319 412-1, che
nel
caso specifico prevede la seguente
composizione:
VATIT-
Questo campo non appare quando
l’auth_type è di tipo Eidas
address address Opzionale, Json contenente i seguenti campi:
street_address,
locality,
postal_code,
country,
digital_address (PEC)
email email Opzionale. Formato standard indirizzo di
posta elettronica.
phone_number phone Opzionale. Numero di telefono cellulare
Tabella 9: Attributi UserInfo
Di seguito un esempio di risposta dell’invocazione UserInfo con scope profile.
18LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
{
"sub":"adac8715-ae9a-45f8-9399-5ac3a747f828",
"name": "MARCO",
"family_name": "ROSSI",
"fiscal_number": " TINIT-marrssg78dsaf7sad8f9",
"preferred_username": "marrssg78dsaf7sad8f9",
"birthdate":"1970-01-01",
"email":"email@email.com"
}
Tabella 10: UserInfo response
Di seguito un esempio di risposta dell’invocazione UserInfo quando l’auth_type è di tipo
Eidas.
{
"sub":"f:e93071f9-9824-436f-9986-
b9da2eb3fe4d:pmrhk43fojxgc3lfei5ceskuf5evil2bjfcfambqgaytmojyg
y4deirmejxgc3lfei5cetdbovzgcirmejzxk4tomfwzfceafwrhjnhxdfgvserf
aWSDqeq23rfrsfgsdgbfcbcghfxgfvsxfgdgd",
"auth_type": "Eidas",
"birthdate": "",
"email_verified": false,
"auth_level": "1",
"name": "MARIO",
"spid_code": "IT/IT/AIDP0009999999",
"preferred_username": "IT/IT/AIDP0009999999",
"family_name": "ROSSI"
}
Tabella 11: UserInfo response per eIDAS
5 Monitoraggio delle applicazioni e logging
E’ importante che le applicazioni integrate nella infrastruttura tengano traccia delle
informazioni di accesso fornite da ARPA al fine di un eventuale riscontro sugli accessi
effettuati dai soggetti.
I dati che suggeriamo vengano memorizzati a livello applicativo e che sono utili al
tracciamo sono i seguenti:
19LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
auth_time data ed ora di autenticazione su ARPA in formato UNIX
fiscal_number codice fiscale in formato unico europeo dell’utente che si è
autenticato
auth_type tipo di strumento utilizzato per l’autenticazione
auth_level livello di autorizzazione utilizzato per l’accesso
authID identificativo della request
Tabella 12: Elenco degli attributi per il tracciamento
5.1 5.1 Utilizzo AuthRefId1
Viene resa disponibile una modalità di correlazione (AuthRefId) che permette ad
un’applicazione di fornire un proprio identificativo di chiamata nelle richieste di
autenticazione inviate ad ARPA.
Per permettere alle applicazioni il tracciamento delle operazioni effettuate dall’utente
prima che sia stato riconosciuto da Arpa, è necessario includere l’attributo AuthRefId.
Questo consente di tracciare, ad esempio:
1. Tutte le attività effettuate dall’utente prima, durante e dopo l’autenticazione
2. Monitorare quanti utenti si fermano alla pagina di login senza effettivamente
autenticarsi
È sufficiente aggiungere il query parameter AuthRefId all’url di redirect valorizzato con
l’identificativo all’interno dell’applicativo.
Supponiamo ad esempio che l’url di redirect sia http://miaapplicazione/callBack dovrà
essere modificata in
http://miaapplicazione/callBack?AuthRefId=VALORE_DESIDERATO
Precisiamo che questo parametro non viene persistito da ARPA ed è pertanto
transiente, in quanto è da intendersi ad uso e consumo del fornitore dell’applicativo,
non di ARPA.
6 Logout
Le applicazioni integrate con ARPA devono implementare correttamente il meccanismo
di Logout.
1
https://oscat.rete.toscana.it/docman/view.php/803/7063/%5BAccessoSicuro+2020%5D++ARPA+-
+MONITORAGGIO+ACCESSI+APPLICATIVI.pdf
20LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
La specifica del Logout per l’ambiente di Staging è la seguente:
POST https://accessosicuro-
trial.rete.toscana.it/auth/realms/arpa/protocol/openid-connect/logout
Authorization: Bearer
Content-Type: application/x-www-form-urlencoded
client_id=&refresh_token= (per client di tipo
"public")
client_id=&client_secret=&refresh_token= (per client "confidential")
Per implementare la funzionalità in ambiente di Produzione:
POST https://accessosicuro.rete.toscana.it/auth/realms/arpa/protocol/openid-
connect/logout
Authorization: Bearer
Content-Type: application/x-www-form-urlencoded
client_id=&refresh_token= (per client di tipo
"public")
client_id=&client_secret=&refresh_token= (per client "confidential")
In alternativa, senza dover fare chiamate REST, redirezionare l'utente alla
seguente url quando questo clicca sul pulsante di Logout:
Staging
https://accessosicuro-trial.rete.toscana.it/auth/realms/arpa/protocol/openid-
connect/logout?redirect_uri=
Produzione
https://accessosicuro.rete.toscana.it/auth/realms/arpa/protocol/openid-
connect/logout?redirect_uri=
21LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
1. Allegato A - Authentication Type
a. Introduzione
In questo allegato presentiamo l’elenco degli strumenti a norma che possono
essere utilizzati per l’autenticazione sulla piattaforma ARPA.
Ogni strumento utilizzato restituisce un insieme di dati descrittivi dell’utente, sia
fisico che giuridico, che possono essere utilizzati per riconoscere e caratterizzare
l’utente stesso.
Il termine ‘strumento di autenticazione’ verrà da ora in poi sostituito con il
termina ‘AuthType’ o ‘Authentication Type’, per dare una sintassi più aderente
a quanto verrà riscontrato nella pratica.
Nel token JWT, troviamo il dato evidenziato in Tabella 1: esempio di JSON con
auth_type
"fiscal_number": "TINIT-FRMTTR76M06B715E",
"sub": "e2385864-6e12-430a-9adc-55915a754454",
"auth_type": "PosteIDPSpid",
"birthdate": "1976-08-06",
"email_verified": false,
"auth_level": "3",
"name": "ETTORE",
"spid_code": "cbc16c17-294e-43d3-a1f1-37f1019adf61",
"preferred_username": "FRMTTR76M06B715E",
"family_name": "FIERAMOSCA",
"email": "trediciitalianicontrotredicifrancesi@hotmail.com"
Tabella 13: esempio con auth_type
Di seguito sono riportati le possibili valorizzazioni di authType in funzione del
metodo di autenticazione utilizzato:
● CNS - Per autenticazioni CNS
● EIDAS - Per autenticazione con Login Eidas (vedi Progetto FICEP)
● CIE - Per autenticazioni CIE
● RegisterSpid - Per autenticazioni SPID con IDP Register
● LepidaSpid - Per autenticazioni SPID con IDP Lepida
● InfocertIDPSpid - Per autenticazioni SPID con IDP Inforcert
● SielteSpid - Per autenticazioni SPID con IDP Sielte
● TimIDPSpid - Per autenticazioni SPID con IDP Tim
● IntesaIDPSpid - Per autenticazioni SPID con IDP Intesa
● PosteIDPSpid - Per autenticazioni SPID con IDP Poste
● ArubaSpid - Per autenticazioni SPID con IDP Aruba
● NamirialSpid - Per autenticazioni SPID con IDP Namirial
22LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
b. Tipologia identità digitali supportate per tipologia di autenticazione
Di seguito sono riportate le tipologie di identità digitali supportate per tipologia
di autenticazione:
● Spid (Sistema Pubblico per l’Identità Digitale)23
○ Identità digitale della persona fisica
○ Identità digitale ad uso professionale della persona fisica4
○ Identità digitale ad uso professionale per la persona giuridica
● CNS (Carta Nazionale dei Servizi)
○ Persona fisica ad uso privato
● CIE (Carta di Identità Elettronica)
○ Persona fisica ad uso privato
● eIDAS (electronic IDentification Authentication and Signature)
○ Persona fisica ad uso privato
Esiste un insieme minimo di attributi che vengono restituiti da tutte le tipologie
di autenticazione, la mappa completa degli attributi restituiti è riportata nel
paragrafo Schema attributi per AuthType.
Per quanto riguarda i nuovi tipi di autenticazione presenti, ovvero eIDAS e Spid-
P, il processo di integrazione rimane invariato.
c. Differenze di base tra gli Authentication Types
L’autenticazione con eIDAS non prevede il recupero del codice fiscale
dell’utente, ma l’utilizzo del campo SPID code: un identificativo associato
univocamente alla coppia che viene autenticata.
In caso di autenticazione con eIDAS è pertanto necessario, come codice unico
di autenticazione, utilizzare il campo ‘spid_code’, che contiene l’identificativo
univoco dell’utente così come valorizzato dalla autenticazione Login EIDAS.
Il campo ‘spid_code’ è valorizzato dagli identity provider SPID secondo le linee
guida. Esempio:
● cbc16c17-294e-43d3-a1f1-37f1019adf61
2
https://www.agid.gov.it/sites/default/files/repository_files/spid-avviso-n18_v.2-
_autenticazione_persona_giuridica_o_uso_professionale_per_la_persona_giuridica.pdf
3
https://www.agid.gov.it/sites/default/files/repository_files/linee_guida_identita_digitale_per_uso_professionale_v.1.0.p
df
4
Identità digitale ad uso professionale della persona fisica e Identità digitale ad uso
professionale per la persona giuridica sono attivati con lo stesso tag Purpose P, pag 2 del documento
https://www.agid.gov.it/sites/default/files/repository_files/spid-avviso-n18_v.2-
_autenticazione_persona_giuridica_o_uso_professionale_per_la_persona_giuridica.pdf
23LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
Per uniformità si è prevista la valorizzazione dello stesso campo anche per
accessi effettuati con CNS e lo stesso sarà valorizzato nella forma:
● arpa-frmttr76m06b715e
Per questo motivo precisiamo che ha senso considerare il suddetto campo solo
in caso di autenticazione con eIDAS o Spid.
Il campo fiscal_number è valido come codice univoco di identificazione dell’utente
come utilizzato fino ad ora per tutti gli altri metodi di autenticazione diversi da
eIDAS.
24LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
d. Schema attributi per Authentication Types
Di seguito gli attributi disponibili in base al tipo di autenticazione utilizzato.
Base Esteso Completo5
CNS SPID CIE eIDAS SPID SPID
fiscalNumber x x x x x
name x x x x x x
familyName x x x x x x
email x x x
spidCode x x x x x x
domicileStreetAddress x x
domicileMunicipality x x
domicileProvince x x
domicileNation x x
companyFiscalNumber x
placeOfBirth x x x
countyOfBirth x x
dateOfBirth x x x
gender x x x
address x x x
mobilePhone x x
idCard x x
expirationDate x x
digitalAddress x x
5
Restituiti sono nel caso di identità digitale professionale
25LINEE GUIDA PER L'INTEGRAZIONE DI
APPLICAZIONI NELLA INFRASTRUTTURA DI
AUTENTICAZIONE DI REGIONE TOSCANA SU
STANDARD OAUTH2
ivaCode x
registeredOffice x
companyName x
Tabella 14: Tabella attributi che posso essere richiesti dagli IDP
26Puoi anche leggere
