Accesso alle API CART
Le API gestite dal CART sono accessibili, esclusivamente tramite protocollo https, a 3 diversi indirizzi:
- api.regione.toscana.it: riservato agli accessi da Internet alle API erogate da Regione Toscana. Su questo endpoint è stato riservato il contesto ‘/sanita’ per le API relative al dominio della Sanità regionale
- api.rt.tix.it: è sostanzialmente un punto di accesso alternativo alle stesse API esposte da api.regione.toscana.it, raggiungibile però esclusivamente dagli applicativi installati sulla rete privata regionale del TIX
- api.rete.toscana.it: è il punto di accesso dedicato alle API delle Amministrazioni del territorio regionale diverse da Regione Toscana; le API di ogni amministrazione sono indirizzate da un contesto con l’identificatore dell’Amministrazione erogatrice della API.
- Es: https://api.rete.toscana.it/CPisa/sample-api/v1/…
Per ognuno di questi punti di accesso sono definiti diversi “canali”, che possono differenziarsi per il livello di servizio offerto o perché dedicati a specifici domini applicativi, o anche per la diversa versione dell’implementazione della stessa infrastruttura CART.
I canali sono individuati da semplici identificatori del tipo “CXX”, che vengono utilizzati come parte dell’endpoint di accesso al servizio, come ad esempio:
- https://api.regione.toscana.it/C01/sample-api/v1/…
- https://api.regione.toscana.it/C02/sample-api/v1/…
- https://api.rete.toscana.it/C01/CPisa/sample-api/v1/…
- https://api.rete.toscana.it/C02/CPisa/sample-api/v1/…
Al momento della richiesta di adesione ad un servizio, il richiedente può chiedere di accedere ad una API utilizzando un applicativo client preesistente, che ovviamente dovrà essere compatibile con le modalità di accesso a quella API, oppure richiedere la registrazione di un nuovo applicativo client. Nel primo caso il CART autorizzerà l’applicativo
indicato all’accesso alla nuova API, mentre nel secondo caso sarà registrato un nuovo client e le credenziali comunicate al richiedente.
La prima modalità è tipicamente utilizzata quando la stessa applicazione ha bisogno di accedere a più API. Naturalmente è sempre possibile usare credenziali multiple per accedere alle diverse API, ma questo rende la gestione delle credenziali ed il monitoraggio degli accessi al servizio certamente più macchinoso, ed è quindi da evitare.
Allo stesso modo è da evitare, per quanto generalmente possibile, l’utilizzo delle stesse credenziali per far accedere applicazioni client diverse ad una stessa API.
In sostanza, ogni singola applicazione client deve essere registrata sul CART alla prima richiesta di accesso, per poter poi ottenere incrementalmente autorizzazioni ulteriori, a mano a mano che sorgano ulteriori esigenze di accesso ad altre API.
Qualunque sia la modalità utilizzata, al termine dell’iter di adesione, l’applicazione client potrà accedere alle API, utilizzando una delle tipologie di accesso previste:
- HTTP Basic, modalità deprecata, ma ancora supportata per compatibilità con il passato. In questa modalità, utenza e password vengono fornite dalla gestione CART al referente dell’adesione.
- HTTPS, in questo caso per l’accesso alle API è richiesta la “client authentication” HTTPS. L’archivio contenente sia la chiave privata che il certificato X509 viene generalmente fornita dal CART tramite comunicazioni sicure con il referente dell’adesione.
- Token Authentication, in questo caso l’accesso all’API è gestito tramite Bearer Authentication. Il Token deve essere rilasciato da una delle fonti di autenticazione riconosciute da Regione Toscana, che possono anche variare per specifiche API. Tipicamente il Token viene ottenuto dal client tramite negoziazione OAUTH2 con gli Authorization Server di Regione Toscana.
Se la richiesta di adesione è riferita ad API che prevedono accesso tramite ‘token‘, i token presentati dai client per l’accesso alla API dovranno avere il nome della API nel claim ‘audience‘ del token presentato per l’accesso, oltre ovviamente a tutti gli altri parametri previsti dalle politiche di accesso all’API (es: spid-level).