In questo articolo esaminiamo il modello di interazione e l’autenticazione del client per richiamare le API.
Le API del gateway sono esposte secondo i pattern definiti nelle Linee Guida Modello di Interoperabilità definite da Agid. I servizi esposti dal gateway sono esposti mediante il pattern Blocking REST.
Per comunicare con il gateway è necessario essere in possesso di 2 certificati X.509 e delle rispettive chiavi private. Il certificato denominato di “autenticazione” viene utilizzato unicamente come certificato client per le chiamate https. Il certificato denominato di “signature” viene utilizzato unicamente per la firma dei token JWT.
Cosa sono i JWT
JWT è un acronimo di JSON Web Token, un sistema di cifratura e di contatto in formato JSON per lo scambio di informazioni tra servizi. Il protocollo prevede la generazione di un token che può essere cifrato e firmato tramite una chiave disponibile solo a colui che lo ha effettivamente generato. L’algoritmo di firma viene elaborato tramite HMAC o con chiavi pubbliche e/o private con standard RSA o ECDSA.
I JWT sono normalmente utilizzati per autenticare un client. Il sistema di funzionamento è abbastanza semplice: il client invia una richiesta al server e questo genera un token di autenticazione che il client utilizzerà tutte le volte che andrà a collegarsi allo stesso nodo.
Il token si compone di tre corpi essenziali:
- Header che contiene le due informazioni base: la tipologia del token e quella dell’algoritmo utilizzato per la cifratura;
- Payload, il blocco che contiene le informazioni di scambio tra le parti. Questo a sua volta si divide in tre parti: parametri registrati, parametri pubblici e parametri privati.
- Signature, la fase di cifratura delle due parti: Payload e Header. Queste vengono dapprima unite e poi sottoposte a un’operazione di crittografia estremamente complessa. Alla fine dell’operazione viene generata una chiave che darà luogo a un token di oltre 200 caratteri.
Il modello di interazione
Ogni invocazione delle API del gateway richiede una chiamata https protetta dal certificato di autenticazione e conterrà negli header 2 token JWT. Il primo è utilizzato per l’autenticazione e contiene i riferimenti all’utente che richiama il servizio e al soggetto interessato.
Il primo è espresso con il Codice Fiscale dell’utente che fa richiesta del servizio di interoperabilità. Il formato di codifica è conforme alle specifiche IHE (ITI TF-3). Il destinatario per cui è stato creato il token viene espresso tramite la base URL del servizio, comprensivo della versione, per esempio https://modipa-val.fse.salute.gov.it/govway/rest/in/FSE/gateway/v1.
Il secondo JWT è di “signature” e contiene rifermenti al documento oggetto delle operazioni. Entrambi i token devono essere firmati utilizzando il certificato “signature”. Vista la dipendenza dei token dai valori specifici di utente/soggetto/documento è necessario generare nuovi JWT per ogni chiamata alle API.
Articoli precedenti:
Come opera il gateway del nuovo FSE – parte prima
I metadati del nuovo FSE – parte seconda
3 – Continua