Esempio dettagliato di una integrazione di un modulo di Opencity Italia che attinge a una API protetta mediante l'API gateway opensource GovWay di Link.it
API privata, che si intende esporre mediante GovWay:
L'API risponde un dato privato se viene correttamente inserito un parametro in get tax_code che identifica il codice fiscale del cittadino che esegue la richiesta:
L'API non ha un controllo interno che permette di rispondere ad ogni cittadino solo con i suoi dati, l'API è aperta e risponde a qualunque chiamata.
In questo esempio si desidera esporre l'API privata su un indirizzo pubblico e filtrare le chiamate in modo che ogni cittadino possa consultare l'API solo per i propri dati.
L'API esposta è la seguente:
Quando viene chiamata quest'ultima url si desidera imporre un controllo sulla la presenza del token JWT e sul parametro della chiamta. La chiamata deve raggiungere l'API privata SOLO se:
il token è presente
il token è validato mediante la chiave pubblica esposta in JWKS
viene passato il parametro tax_code in GET
il parametro tax_code corrisponde al valore username del token
Quest'ultimo punto è il più importante perché ci da la certezza che il cittadino che sta facendo la richiesta è lo stesso che si è autenticato.
E' necessario creare una token policy, che poi verrà assegnata all'erogazione delle API
Il file jwks è stato scaricato da https://servizi.comune-qa.bugliano.pi.it/.well-known/jwks.json e inserito in un path raggiungibile da GovWay: nel nostro caso essendo GovWay installato con Docker abbiamo fatto uso della direttiva volumes per condividere il file con il container di GovWay.
Fare attenzione inoltre che il kid della chiave pubblica è specifico per ogni tenant e deve essere quello corretto.
Predisposta la policy deve essere applicata all'Erogazione API
Il controllo del contenuto viene fatto imponendo che l'informazione riportata nel token (${tokenInfo:username}) e quella inserita come parametro GET della chiamata (${query:filter[tax_code]}) abbiano lo stesso valore. Resta inteso che il valore nel token è vincolato dalla piattaforma, mentre il parametro tax_code è scelto da chi ha progettato l'API che viene protetta.
A questo punto la configurazione è completa.
In questa sezione viene descritta la modalità di integrazione con un servizio di terze parti protetto da autenticazione tramite il token JWT dell'utente.
Dataset e micro servizi esterni alla piattaforma possono essere facilmente integrati tramite il flusso di autenticazione basato su JWT (JSON Web Token) e JWKS (JSON Web Key Set)
Questo flusso di autenticazione prevede alcuni passaggi chiave e interazioni tra:
client (browser dell'utente)
area personale
micro servizio esterno
Di seguito il processo punto per punto:
Il client invia una richiesta all'area personale per ottenere un JWT, spesso includendo le credenziali dell'utente o altre forme di autorizzazione.
Come descritto nella sezione Single Sign-On è possibile per un utente autenticato richiedere un token di autenticazione per la propria sessione.
Questa operazione può essere effettuata facendo una chiamata alle API:
oppure come utente non autenticato effettuando una chiamata POST alle API
L'area personale autentica il client, genera un JWT e lo firma con una chiave privata.
Il token viene quindi restituito al client.
Il client invia una richiesta al micro servizio esterno per accedere a una risorsa protetta, includendo il JWT nell'intestazione Authorization.
Per verificare la validità del token il micro servizio esterno deve:
Estrarre il JWT dalla richiesta
Recuperare il JWKS dall'area personale, il JWKS contiene le chiavi pubbliche necessarie per verificare la firma del JWT.
Verificare la firma del JWT e convalidare le sue richieste
L'area personale espone per ogni sua istanza il JWKS all'indirizzo:
https://instance_url/.well-known/jwks.json
Ad esempio:
In base alla validità del JWT il micro servizio esterno concede o nega l'accesso alla risorsa richiesta.
Oltre alla validità del token si possono verificare le affermazioni in esso contenute.
Il payload del token prodotto dall'area personale presenta delle informazioni utili a capire se quello specifico utente oltre ad avere un token valido ha i permessi per ottenere la risorsa richiesta.
Di seguito un esempio di payload del token
