Strumenti

L’uso degli ‘scope’ dei token ARPA per l’accesso alle API del CART

Lo schema seguente mostra il ruolo degli API Gateway del CART nei processi di autenticazione ed autorizzazione all’accesso alle API da parte delle applicazioni client.

Gli applicativi fruitori possono utilizzare due diversi paradigni di autenticazione:

• uso di credenziali TLS, fornite direttamente dal client tramite protocollo https (MTLS);
• token di accesso rilasciati dagli Authorization Server di ARPA.

L’accesso mediante protocollo https prevede che sussista una relazione di trust tra applicativo fruitore ed API Gateway del CART, che viene preventivamente stabilito in fase di richiesta di adesione al servizio tramite lo scambio dei certificati. Il CART è così in grado di identificare puntualmente l’applicativo ed applicare i criteri di autorizzazione previsti per l’accesso alle API sulla base dell’identità del client fruitore.

L’accesso mediante token OAuth2 prevede invece che il client ottenga un ‘access token’ dagli Authorization Server di ARPA, da utilizzare come credenziale per l’accesso alle API del CART.

In questo articolo ci focalizziamo su questa seconda modalità di accesso, per discutere come sia possibile utilizzare alcune informazioni aggiuntive contenute nei token Oauth2 per ottenere modalità evolute di autorizzazione all’accesso alle API, sulla base dei ruoli degli utenti.

L’uso degli Scope per il controllo degli accessi alle API

Lo ‘scope’ è uno specifico parametro del token ottenuto da ARPA, il cui valore indica le finalità per cui il token viene rilasciato. Questo parametro viene utilizzato sulla piattaforma CART per permettere di differenziare l’accesso a diverse risorse della stessa API, in funzione dei ruoli degli utenti dell’Applicazione Client.

Possiamo ad esempio considerare l’accesso ad una API del fascicolo sanitario, che permetta ai cittadini di accedere esclusivamente in lettura ai propri dati sanitari e ai medici di accedere anche in scrittura. Si tratta ovviamente di una estrema semplificazione, ma utile ad esprimere il concetto.

Come primo step, l’interfaccia della API dovrà essere progettata per distinguere le API a cui possono accedere i cittadini da quelle a cui possono accedere solo i medici. Il progettista può quindi definire due diversi valori di scopo dei token, ad esempio ‘fascicolo-consulta’ e ‘fascicolo-modifica’, e assegnare ad ogni risorsa lo ‘scope’ necessario per l’accesso. Immaginando che l’interfaccia sia espressa tramite lo standard OpenAPI, questa indicazione può essere fornita utilizzando la funzionalità dei ‘security scheme’ di OpenAPI che permette di associare specifici valori dello ‘scope’ del token alle singole risorse della API.

Successivamente, al momento della richiesta di registrazione dell’API su CART, il richiedente, oltre a fornire l’interfaccia OpenAPI, dovrà indicare, per ogni valore dello scope previsto dalla propria API, il ruolo o la combinazione di ruoli e di attributi utente necessari per il rilascio di quel valore nei token di accesso. Nel nostro esempio potrà quindi indicare che il valore ‘fascicolo-consulta’ potrà essere rilasciato a tutti i cittadini, mentre il valore ‘fascicolo-modifica’ dovrà essere rilasciato solo a utenti con il ruolo ‘medico’.

L’applicazione client, al momento della richiesta del token, potrà utilizzare le modalità standard previste da OAuth2 per richiedere ad ARPA che lo ‘scope’ venga popolato con i valori necessari per l’accesso alle API di proprio interesse, nel nostro caso ‘fascicolo-consulta’ e ‘fascicolo-modifica’.

ARPA, dopo aver autenticato l’utente, verificherà se l’utente abbia o meno i ruoli per ottenere i valori di ‘scope’ richiesti, facendo riferimento al mapping tra scope e attributo indicati in fase di richiesta di registrazione dell’API.

L’applicazione client otterrà quindi un token con un valore di ‘scope’ che sarà popolato con l’elenco “‘fascicolo-consulta’, ‘fascicolo-modifica’” per i medici e con il solo ‘fascicolo-consulta’ per il resto degli utenti.

L’applicazione client potrà ora invocare le API del fascicolo esposte dal CART utilizzando il token ottenuto da ARPA. I gateway del CART verificheranno che il token sia valido e che lo ‘scope’ contenga il valore previsto per l’accesso alla specifica risorsa invocata; solo in questo caso l’accesso alla API sarà consentito.

Di fatto, utilizzando lo ‘scope’ del token, è stato possibile realizzare una autorizzazione per ruolo nell’accesso alle risorse di una API.