API – Application Programming Interface – Prima Parte

Secondo esempio: richiesta di un area di occupazione del suolo pubblico per evento culturale, manifestazione o area di mercato.

In questo secondo esempio, un po’ più complesso, l’obiettivo è quello di poter eseguire delle interrogazioni su alcuni metadati presenti nelle istanze (richieste) di occupazione del suolo pubblico eseguite per eventi culturali, manifestazioni o aree di mercato. Ovviamente, siamo nell’ambito di una richiesta di una pubblica amministrazione, per esempio un Comune.

Ma da dove derivano tali dati di occupazione del suolo pubblico?

Una volta individuata l’area del suolo pubblico specifica, un utente o meglio, il richiedente, che più semplicemente è chi esegue la richiesta di occupazione del suolo pubblico per i motivi specificati nel titolo del paragrafo, può procedere con l’invio della richiesta di occupazione del suolo pubblico attraverso un portale delle richieste già esistente. Quest’ultimo, il portale delle richieste, non avendo dei riferimenti specifici nemmeno dell’applicativo, non resta che immaginarlo, e comunque non è oggetto di descrizione approfondita di questo articolo.

La richiesta dell’utente verrà “inserita” in una nuova piattaforma di gestione del suolo pubblico disponibile per le PA nel portale PDND (Piano Digitale Nazionale per i Dati) nell’ottica di condividerla ad altre amministrazioni pubbliche (PA). Per l’obiettivo che ci siamo posti, bisogna creare un’API di inserimento della richiesta, proveniente dal portale delle richieste, alla nuova piattaforma. Quindi, ora parleremo solo dell’API che svolgerà tale compito.

Per prima cosa, cerchiamo di capire come gestire il meccanismo di autenticazione dell’utente presupponendo che l’utente si sia già autenticato al portale delle richieste (indicato con il nome Portale nel diagramma di sequenza successivo) con autenticazione OAUTH2 e LDAP. In tale situazione, l’API dovrà essere in grado di verificare e validare il token inviato con la richiesta dal portale delle richieste. Ecco di seguito un breve diagramma di sequenza di quanto descritto.

I seguenti sono gli “oggetti” che costituiscono il diagramma di sequenza mostrato nell’immagine precedente.

1. Lo “User” rappresenta l’utente che fa una richiesta all’API e che accede al Portale delle richieste.
2. Il “Portale” è l’applicazione Portale delle richieste già funzionante in cui l’utente si autentica tramite protocollo OAUTH2 e LDAP su Azure AD.
3. Il “Server OAuth2” È responsabile dell’autenticazione e dell’autorizzazione degli utenti. Gestisce le richieste di autenticazione inoltrate dal portale, verifica le credenziali con il server LDAP e, se necessario, richiede il consenso dell’utente per determinate autorizzazioni. Una volta completato il processo di autenticazione, emette un token di accesso attraverso Azure AD.
4. Il “Server LDAP” È un server di directory che contiene informazioni sugli utenti e i loro ruoli/privilegi. Il server OAuth2 consulta il server LDAP per verificare le credenziali fornite dall’utente durante il processo di autenticazione.
5. “Azure AD“. Azure Active Directory (Azure AD) è un servizio di identità basato su cloud. Nel contesto di questo diagramma, Azure AD collabora con il server OAuth2 per emettere token di accesso e successivamente valida questi token quando l’API li riceve nelle richieste.
6. “API”. Rappresenta l’endpoint o il servizio funzionate grazie al framework Express su NodeJS che il portale chiama per eseguire operazioni specifiche, come la richiesta di occupazione del suolo. L’API protegge le sue risorse verificando i token di accesso in ogni richiesta e assicurandosi che l’utente o il sistema che effettua la richiesta abbia le autorizzazioni appropriate.
   

Ecco la spiegazione dettagliata del diagramma di sequenza presente nell’immagine precedente:

• Lo “User” inizia il processo di autenticazione accedendo al portale delle richieste fornendo le proprie credenziali
• Il “portale delle richieste” inoltra la richiesta di autenticazione al server OAuth2 per iniziare il processo di autenticazione OAuth2.
• Il “server OAuth2“, per verificare le credenziali dell’utente, si interfaccia con il “server LDAP”. Il “server LDAP” è responsabile della verifica delle credenziali dell’utente.
• Il “server LDAP” risponde al “server OAuth2” indicando se le credenziali sono valide o meno.
• Se l’utente non ha ancora concesso le autorizzazioni necessarie, il “server OAuth2” informa il portale delle richieste di richiedere il consenso dell’utente per le autorizzazioni necessarie.
• Il “portale delle richieste” mostra all’utente una pagina di consenso, dove l’utente può vedere e approvare le autorizzazioni richieste.
• Lo “User” conferma il consenso alle autorizzazioni richieste.
• Con il consenso dell’utente, il portale delle richieste richiede al server OAuth2 un token di accesso.
• Il “server OAuth2” si interfaccia con “Azure AD” per emettere un token di accesso per l’utente.
• “Azure AD” fornisce il token di accesso al portale delle richieste .
• Con il token di accesso valido, l’utente ha ora accesso al “portale delle richieste” e può iniziare a utilizzare le sue funzionalità.
• L’utente compila una richiesta di occupazione del suolo attraverso il “portale delle richieste”.
• Il “portale delle richieste” effettua una chiamata all’API protetta (quella che svilupperemo), includendo il token di accesso come Bearer token nell’header della richiesta.
• L'”API” riceve la richiesta e valida il token di accesso con “Azure AD“.
• Azure AD risponde all’API indicando se il token è valido o meno.
• L'”API“, dopo aver elaborato la richiesta, invia una risposta al “portale delle richieste” , che può contenere i dati richiesti o eventuali errori.
• Il “portale delle richieste” mostra all’utente il risultato della sua richiesta, che può essere la conferma dell’occupazione del suolo o un messaggio di errore.

Pagina Successiva | Pagina Precedente