> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/stanza-del-cittadino/sviluppatori-e-partner-tecnologici/integrazioni/integrazione-di-un-servizio-di-terze-parti-protetto-da-autenticazione/esempio-con-govway.md). # Esempio con GovWay Esempio dettagliato di una integrazione di un modulo di Opencity Italia che attinge a una API protetta mediante l'API gateway opensource GovWay di Link.it API privata, che si intende esporre mediante GovWay: ``` https://192.168.1.111:8000/conti-correnti ``` L'API risponde un dato privato se viene correttamente inserito un parametro in get tax\_code che identifica il codice fiscale del cittadino che esegue la richiesta: ``` https://192.168.1.111:8000/items/conti-correnti?tax_code=AAABBBXX... ``` L'API non ha un controllo interno che permette di rispondere ad ogni cittadino solo con i suoi dati, l'API è aperta e risponde a qualunque chiamata. In questo esempio si desidera esporre l'API privata su un indirizzo pubblico e filtrare le chiamate in modo che ogni cittadino possa consultare l'API solo per i propri dati. L'API esposta è la seguente: ``` https://govway-qa-out.boat.opencontent.io/govway/Ente/directus/v1 ``` Quando viene chiamata quest'ultima url si desidera imporre un controllo sulla la presenza del token JWT e sul parametro della chiamta. La chiamata deve raggiungere l'API privata SOLO se: 1. il token è presente 2. il token è validato mediante la chiave pubblica esposta in [JWKS](https://servizi.comune-qa.bugliano.pi.it/.well-known/jwks.json) 3. viene passato il parametro `tax_code` in GET 4. il parametro tax\_code corrisponde al valore `username` del token Quest'ultimo punto è il più importante perché ci da la certezza che il cittadino che sta facendo la richiesta è lo stesso che si è autenticato. ### Configurazione

Aggiungere la definizione dell'API: per farlo sarà necessario caricare il file Open API 3 della definizione dell'API stessa.

Creare una API in Erogazione che esponga l'API che si desidera proteggere: si usa la definizione dell'API configurata allo step precedente e si impostano la URL di invocazione e la url del servizio interno che espone l'API (connettore)

E' necessario creare una token policy, che poi verrà assegnata all'erogazione delle API

Creazione token policy: fare attenzione a tutti i campi evidenziati. Lo username verrà usato per fare il controllo di accesso.

Il file jwks è stato scaricato da e inserito in un path raggiungibile da GovWay: nel nostro caso essendo GovWay installato con Docker abbiamo fatto uso della direttiva `volumes` per condividere il file con il container di GovWay. Fare attenzione inoltre che il `kid` della chiave pubblica è specifico per ogni tenant e deve essere quello corretto. Predisposta la policy deve essere applicata all'Erogazione API

Configurazione dell'Erogazione creata in precedenza

Si accede alle configurazioni necessarie dalla sezione "Controllo Accessi" dell'Erogazione API

Il controllo prevede la Policy predisposta agli step precedenti, la validazione del token e la presenza del claim username. Infine viene inserito il controllo sul contenuto come indicato nell'immagine.

Il controllo del contenuto viene fatto imponendo che l'informazione riportata nel token (`${tokenInfo:username}`) e quella inserita come parametro GET della chiamata (`${query:filter[tax_code]}`) abbiano lo stesso valore. Resta inteso che il valore nel token è vincolato dalla piattaforma, mentre il parametro `tax_code` è scelto da chi ha progettato l'API che viene protetta. A questo punto la configurazione è completa. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.opencityitalia.it/stanza-del-cittadino/sviluppatori-e-partner-tecnologici/integrazioni/integrazione-di-un-servizio-di-terze-parti-protetto-da-autenticazione/esempio-con-govway.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.