OpenAPI Checker: il verificatore delle interfacce digitali (API)
Uno strumento open source per verificare il rispetto delle Linee Guida sull’interoperabilità
Un nuovo strumento per l’interoperabilità
Verso l’interoperabilità e oltre: le interfacce digitali (API)
L’interoperabilità all’interno della Pubblica Amministrazione è un requisito essenziale per facilitare lo scambio di informazioni e dati nella sfera pubblica e, di conseguenza, aiutare i cittadini e gli enti a risparmiare tempo, denaro e risorse.
Partendo da questo presupposto, Agid, in collaborazione con il Dipartimento per la trasformazione digitale, ha pubblicato le Linee guida sull’Interoperabilità tecnica delle Pubbliche Amministrazioni e quelle sulle Tecnologie e standard per la sicurezza dell’interoperabilità tramite API dei sistemi informatici. Lo scopo dei documenti è quello di agevolare la collaborazione tra due o più pubbliche amministrazioni e tra queste e soggetti terzi, per mezzo di soluzioni tecnologiche che assicurano l’interazione e lo scambio di informazioni senza vincoli sulle implementazioni, evitando così integrazioni ad hoc. Nello specifico, i documenti promuovono lo sviluppo di interfacce digitali (API) coerenti e l’applicazione di pratiche di progettazione sicura.
Uno strumento open source per migliorare l’interoperabilità
Il Dipartimento, nell’intento di semplificare il lavoro di adeguamento alle linee guida e di messa in sicurezza delle API da parte degli enti e dei loro fornitori, ha creato uno strumento di supporto: l’“OpenAPI Checker”. Si tratta di un verificatore — per ora in una versione beta — che analizza le specifiche di un’API REST (ossia conforme allo stile architetturale Representational State Transfer) e individua eventuali difformità rispetto alle regole tecniche Agid. Il verificatore è uno strumento automatico sviluppato secondo i principi dell’open source che serve a correggere gli errori più diffusi in fase di progettazione di un’API. Il verificatore è basato su una libreria di validazione open source, integrata da una serie di regole basate sul lavoro di interoperabilità fatto dal Dipartimento e da Agid.
Si tratta di un lavoro in continuo miglioramento: le regole possono essere via via ampliate e arricchite nel tempo ponendo particolare attenzione a fornire risposte adeguate alle minacce di sicurezza informatica in costante evoluzione.
È importante sottolineare che lo strumento può essere utile non solo alle PA, ma anche a organizzazioni terze e alle imprese: le regole del verificatore, infatti, sono basate su buone pratiche a livello globale per lo sviluppo di API (ad esempio le “Best Current Practices” per lo scambio di informazioni di autenticazione ed autorizzazione).
Com’è fatto il verificatore API
Il verificatore è composto da un’interfaccia web realizzata secondo i Kit di Designers Italia e da una serie di regole che vengono verificate da Spectral, un motore open source per la validazione statica (anche detto “linter”) di file OpenAPI.
Lo sviluppo delle regole avviene separatamente dal front-end e la messa in produzione dell’interfaccia web avviene attraverso una pipeline di continuous integration (CI). Questa metodologia di sviluppo permette di utilizzare la versione delle regole pubblicata dal Dipartimento anche al di fuori della web application, oppure di integrarle, sempre tramite CI, in altri tool e prodotti, con la certezza di utilizzare sempre l’ultima versione.
Il set di regole può essere utilizzato anche in locale installando spectral. Ad esempio, per verificare l’aderenza agli standard di sicurezza (spectral-security.yml) di un file OpenAPI v3 (my-oas.yml) basta lanciare da terminale:
$ spectral lint -r https://italia.github.io/api-oas-checker/spectral-security.yml my-oas.yml
È possibile anche estendere i profili attuali e proporre nuove regole, seguendo gli esempi presenti nel repository.
Come funziona il verificatore API
Dato un file in formato OpenAPI 3 che descrive la specifica di un’API, il verificatore controlla la sua conformità rispetto a una serie di regole prestabilite: per ogni regola non rispettata, mostra l’errore e la riga del file a cui si riferisce.
Per ogni regola, il verificatore può mostrare ulteriori informazioni, inclusi riferimenti ad altre pagine web, e un link ai canali di discussione nella community di Developers Italia per ottenere un supporto interattivo.
Usando il verificatore è possibile migliorare la qualità e la sicurezza delle proprie API. Inoltre i controlli:
- segnalano l’assenza di metadati fondamentali, come i termini d’uso e la versione;
- verificano l’utilizzo corretto del protocollo HTTP o l’assenza del TLS;
- supportano il design coerente rispetto ai metodi e ai nomi dei campi, del caching e del rate-limiting.
In riferimento alla cybersecurity, sono stati aggiunti dei controlli ulteriori che aiutano a verificare la presenza di schemi dati non adeguatamente definiti e l’uso corretto dei token di autenticazione e autorizzazione basati su JSON Web Token (RFC 7519).
Esempi di utilizzo
Diversi enti utilizzano già la prima versione del verificatore per adeguare le proprie API alle regole tecniche, non solo verificando la loro correttezza, ma anche integrando i file con le regole direttamente nei loro sistemi di continuous integration. Ne è un esempio l’Istituto Nazionale di Geofisica e Vulcanologia. Altre organizzazioni invece lo utilizzano per allineare le specifiche di sviluppo dei servizi con altri enti. La fondazione no profit OWASP (Open Web Application Security Project), inoltre, usa le regole di sicurezza e di conformità con il protocollo HTTP per il suo progetto APICheck. Il lavoro del Dipartimento sta quindi contribuendo, anche se indirettamente, a rendere più sicure le API che fanno affidamento su questo progetto.
Prossimi passi
Il Dipartimento intende promuovere l’utilizzo dello strumento tra gli enti pubblici e i loro fornitori. Intende inoltre coinvolgere le community di esperti di sicurezza, di API e gli altri Paesi Membri dell’Unione Europea nella stesura e nel miglioramento delle regole del verificatore.
Regole comuni, infatti, semplificano la sicurezza e l’interoperabilità dei servizi digitali non solo nazionali ma anche transfrontalieri, a vantaggio di tutti.
Lo sforzo è diretto quindi a creare una comunità che lavori all’identificazione e all’implementazione di ulteriori regole di sicurezza per fornire al Paese uno strumento sempre più utile.
Ti aspettiamo!
