Validazione dei Certificati SSL/TLS

Le API della PA sono quasi sempre protette da certificati X.509. Il tuo client deve essere in grado di validare la catena di certificazione del server.

• Verifica che il certificato del server sia firmato da una CA (Certificate Authority) attendibile.
• In ambiente Java (Spring Boot), assicurati che il truststore contenga i certificati root necessari.
• Se l'API richiede mutual TLS (mTLS) - sempre più comune per servizi critici - dovrai configurare anche un keystore con il tuo certificato client.

Controllo delle Versioni e Ambiente (Env)

Un errore comune è gestire la configurazione in modo statico. Le API della PA possono subire aggiornamenti (versioning). È prassi consigliata implementare la gestione delle configurazioni per ambiente:

Utilizzare file di configurazione separati (es. application-dev.yml e application-prod.yml) evita che credenziali di produzione finiscano accidentalmente in ambiente di test.

Errori Comuni nella Configurazione dei Metadati

Ecco gli errori che ritardano maggiormente l'integrazione con le API PA:

• Redirect URI mismatch: Un errore di battitura o l'uso di HTTP invece di HTTPS causa un errore "redirect_uri_mismatch" bloccante.
• Scopes mancanti: Se l'applicazione non dichiara uno scope, l'API restituirà un errore 403 (Forbidden) anche se il token è valido.
• Formattazione del Client Secret: Alcuni sistemi richiedono che il Client Secret sia URL-encoded se contiene caratteri speciali.

Checklist Finale di Configurazione

Prima di procedere all'autenticazione effettiva, verifica di aver completato questi punti:

1. Registrazione: L'applicazione è registrata sul portale dell'Ente e lo stato è "Attivo"?
2. Credenziali: Hai salvato Client ID e Client Secret in modo sicuro?
3. Redirect URI: È stato approvato dall'Ente o correttamente configurato nei metadati?
4. Endpoints: Gli URL di authorize e token sono corretti per l'ambiente target?
5. Scopes: Hai mappato gli scope necessari alle funzionalità della tua applicazione?

Una volta superata questa fase, sei pronto per passare al flusso di autenticazione vero e proprio: la richiesta di autorizzazione e lo scambio del codice per l'access token.

Ottenere le credenziali: Client ID e Client Secret sul portale dell'Identity Provider

Configurazione dei Redirect URI e Strict TLS: Vincoli di sicurezza

Nella fase di implementazione di un sistema basato su OAuth 2.0, la configurazione sicura dei Redirect URI è cruciale per prevenire attacchi di tipo phishing o hijacking dell'authorisation code. Il flusso di autorizzazione deve terminare esclusivamente su endpoint di dominio attendibili e preventivamente autorizzati. Il Redirect URI deve essere specificato sia nella richiesta di autorizzazione (request) che durante la registrazione del client presso l'Identity Provider (IdP) della PA. È buona norma utilizzare URL assoluti e specificare esplicitamente il protocollo (https) e la porta, evitando asterischi o pattern generici che potrebbero essere sfruttati da attori malevoli.

In un contesto di integrazione API con la Pubblica Amministrazione, l'utilizzo di Strict Transport Security (HSTS) è altresì obbligatorio. L'Header HTTP Strict-Transport-Security deve essere configurato sui server che ospitano i Redirect URI, imponendo la connettività esclusiva via TLS. Questo vincolo previene attacchi di tipo SSL Stripping e garantisce che il browser non accetti connessioni non cifrate verso il dominio di reindirizzamento. Il TTL (Time To Live) dell'header dovrebbe essere impostato su un periodo adeguato (es. 6 mesi o più), includendo l'istruzione 'includeSubDomains' se necessario, e il parametro 'preload' solo se si vuole sottoporre il dominio alla inclusione nelle liste predefinite dei browser.

Un ulteriore vincolo di sicurezza, spesso richiesto nei Regolamenti di gestione del servizio (SLA) della PA, è l'adozione del TLS 1.2 o superiore. È necessario disabilitare sul server tutte le versioni precedenti del protocollo (SSL v3, TLS 1.0, TLS 1.1) e le cifre considerate deboli (come RC4 o CBC). Una configurazione errata del TLS, infatti, potrebbe compromettere la confidenzialità dei token scambiati durante il flusso OAuth 2.0. Al termine della configurazione, è indispensabile eseguire un audit degli endpoint utilizzando strumenti di scanning TLS (es. SSL Labs) per verificare la conformità ai vincoli di sicurezza della Pubblica Amministrazione.

Step 1: L'Autenticazione (Richiesta di Autorizzazione)

Step 1: L'Autenticazione (Richiesta di Autorizzazione)

L'integrazione con le API della Pubblica Amministrazione, soprattutto quelle legate a sistemi sanitari e amministrativi, richiede un approccio rigoroso alla sicurezza. In questa prima fase, configuriamo il flusso di autenticazione OAuth 2.0. Il processo inizia con la richiesta di autorizzazione, ovvero quando l'applicazione richiede all'utente (tramite il browser) il permesso di accedere ai suoi dati tramite l'API.

Questa fase è critica perché coinvolge direttamente l'utente finale, che deve comprendere cosa sta concedendo e a chi. Per semplificare la gestione dell'autenticazione, utilizzeremo un flusso Authorization Code Grant con PKCE (Proof Key for Code Exchange), considerato lo standard più sicuro per applicazioni di tipo web e mobile, e l'unico accettato dalla maggior parte degli endpoint tecnologici della PA.

Generazione del Code Verifier e Code Challenge (PKCE)

Per evitare attacchi di tipo "interception" sul codice di autorizzazione, generiamo dinamicamente due parametri crittografici:

1. Code Verifier: Una stringa casuale complessa (min. 43 caratteri, max. 128).
   Esempio generico: wcZb9v2A...
2. Code Challenge: Il risultato della funzione di hash SHA-256 applicata al Code Verifier, codificata in Base64URL.

Questo passaggio è obbligatorio per gli endpoint moderni e garantisce che chi richiede il token finale sia effettivamente colui che ha generato la richiesta iniziale.

Costruzione dell'URL di Autorizzazione

L'utente viene reindirizzato a questo URL (solitamente tramite un pulsante "Accedi con SPID/CIE" nella tua UI). L'URL deve essere costruito con i seguenti parametri query:

• response_type=code: Indica che vogliamo un codice di autorizzazione.
• client_id: Il tuo Client ID registrato.
• redirect_uri: L'URI di ritorno.
• scope: I permessi richiesti (es. openid profile email o specifici per l'API della PA, come dati_sanitari).
• state: Un valore univoco per prevenire CSRF (Cross-Site Request Forgery). Va salvato in sessione e verificato al ritorno.
• code_challenge: Il valore calcolato precedentemente.
• code_challenge_method=S256: Specifica l'algoritmo usato per il challenge.

https://auth.ente-pa.it/authorize?
  response_type=code&
  client_id=ABC123XYZ&
  redirect_uri=https://tua-app.it/callback&
  scope=openid%20profile&
  state=xyz123&
  code_challenge=E9Mel...&
  code_challenge_method=S256

Una volta che l'utente autorizza l'accesso, il browser viene reindirizzato al tuo redirect_uri con due parametri query cruciali: code (il codice di autorizzazione a tempo vita breve) e state (che devi confrontare con quello salvato in sessione per validare l'integrità della richiesta).

Con il codice di autorizzazione in mano, sei pronto per il prossimo step: lo scambio del codice per l'Access Token e l'ID Token.

Costruzione dell'URL di autenticazione (Authorization Endpoint)

Costruzione dell'URL di autenticazione (Authorization Endpoint)

L'URL dell'authorization endpoint è il primo tassello dell'intero flusso OAuth 2.0. Lo si ottiene dal provider di autenticazione della PA (spesso l'Identity Provider o IdP) e integra parametri fondamentali. Un tipico endpoint per la Pubblica Amministrazione italiana ha questa struttura:

https://idp.pa.gov.it/authorize
  ?response_type=code
  &client_id=TUO_CLIENT_ID
  &redirect_uri=URL_DI_REDIRECT_CODIFICATO
  &scope=openid%20profile%20email
  &state=CASUALE_UNIVOCO
  &nonce=CASUALE_UNIVOCO

Analizziamo i campi chiave:

• response_type=code: richiede un codice di autorizzazione (grant code), la scelta più sicura per server-side.
• client_id: l'identificativo dell'applicazione, fornito dalla PA in fase di registrazione.
• redirect_uri: l'indirizzo a cui l'utente sarà reindirizzato dopo l'autenticazione (deve coincidere con quello registrato, percent-encodato).
• scope: definisce i permessi richiesti. Per l'integrazione API PA, includi openid e gli scope specifici del servizio (es. anagrafica o pagamenti).
• state: valore criptograficamente forte per prevenire CSRF. Deve essere verificato nella callback.
• nonce: protegge against replay attack sugli ID token (se usi OpenID Connect).

Importante: l'URL deve essere sempre costruito server-side per proteggere client_secret e parametri sensibili. Usa una libreria OAuth per l'encoding corretto dei caratteri speciali. Prima di invocare l'endpoint, verifica che l'HTTPS sia attivo e che il certificato del IdP sia valido. Per approfondire la configurazione e ricevere supporto tecnico mirato all'ambiente PA, contatta Culture Digitali Srl: i nostri esperti ti guideranno nella configurazione sicura e conforme.

Parametri obbligatori: response_type, client_id, redirect_uri, scope, state e nonce

Parametri obbligatori: response_type, client_id, redirect_uri, scope, state e nonce

Per garantire un flusso di autenticazione robusto e conforme agli standard nazionali (come le Linee guida per l'interoperabilità delle Pubbliche Amministrazioni e il PDND - Piattaforma Digitale Nazionale Dati), l'implementazione OAuth 2.0 richiede il passaggio di specifici parametri durante la richiesta di autorizzazione. Questi parametri costituiscono il "contratto" tra il tuo servizio (Client) e il server dell'Identity Provider (IdP) della PA.

Ecco il significato e l'uso corretto di ciascun parametro obbligatorio:

• response_type: Definisce il flusso di concessione (grant flow) e il tipo di credenziali che il client riceverà. Per l'accesso alle API della PA, il valore standard e obbligatorio è code, che attiva il flusso di autorizzazione basato su codice (Authorization Code Grant), il più sicuro per le applicazioni server-side.
• client_id: È l'identificativo pubblico univoco del tuo servizio, rilasciato dall'ente certificatore durante la fase di onboarding. Deve essere inviato in chiaro per permettere all'IdP di riconoscere l'applicazione che richiede l'accesso.
• redirect_uri: L'URL a cui l'utente sarà reindirizzato dopo aver concesso il consenso (o negato l'accesso). È fondamentale che questo URL sia stato preventivamente registrato e validato nell'area di amministrazione del tuo profilo client per evitare attacchi di tipo open redirect. La redirect_uri deve essere sempre URL-encoded.
• scope: Specifica i permessi granulari che la tua applicazione richiede. In ambito PA, gli scope sono spesso definiti a livello nazionale (es. openid, profile, email per i dati base, o scope specifici per accesso a dati sanitari, catastali, ecc.). La separazione con spazio è lo standard comune.
• state: È un parametro di sicurezza cruciale. Il client deve generare un valore univoco, criptograficamente casuale e legarlo alla sessione dell'utente. L'IdP restituirà questo stesso valore nella risposta. Verificando che corrisponda, il client previene attacchi di tipo Cross-Site Request Forgery (CSRF).
• nonce: Obbligatorio solo se si usa OpenID Connect (OIDC). È un valore usato per mitigare gli attacchi di replay. Il client lo genera e lo invia nella richiesta; l'IdP lo inserirà nel JWT (ID Token) restituito. Il client deve verificare che il nonce nel token corrisponda a quello inviato.

L'omissione o la configurazione errata di uno di questi parametri comporterà quasi sempre un errore di autenticazione. Per garantire la massima sicurezza, è buona norma validare rigorosamente i valori ricevuti e utilizzare sempre HTTPS per la trasmissione dei parametri.

Step 2: Lo Scambio del Codice (Token Endpoint)

curl -X POST "https://api.ente-pubblico.it/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AQoM...xyz" \
-d "redirect_uri=https://tua-app.com/callback" \
-d "client_id=CLIENT_ID_123" \
-d "client_secret=CLIENT_SECRET_456"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "AOEOul...ZXY",
  "scope": "api_pa_conservazione"
}

La richiesta POST al Token Endpoint: parametri e Basic Auth

La richiesta POST al Token Endpoint: parametri e Basic Auth

Il primo passo concreto dello scambio OAuth 2.0 è la richiesta POST verso il Token Endpoint del server di autenticazione della PA. Si tratta di una chiamata sincrona che non prevede l’uso di browser e che deve avvenire esclusivamente in ambiente server.

1. Endpoint e formato
L’endpoint è solitamente https://idserver.pa.gov.it/oauth/token e la richiesta deve essere inviata con header Content-Type: application/x-www-form-urlencoded. I parametri vanno codificati nel corpo della richiesta, non nell’URL.

2. Parametri obbligatori
- grant_type=client_credentials: è il flusso machine-to-machine richiesto per le integrazioni server-to-server.
- scope: definisce i permessi richiesti (es. anagrafica:lettura o pagamenti:scrittura). Va allineato con quelli concessi nella fase di onboarding.

3. Autenticazione Basic Auth
L’identificazione del client avviene tramite Basic Authentication nell’header HTTP. Si crea la stringa “client_id:client_secret”, la si codifica in Base64 e si aggiunge l’header:
Authorization: Basic base64(client_id:client_secret)
Attenzione: non includere questa codifica nel corpo della richiesta. Usa esclusivamente HTTPS e proteggi il client_secret come un segreto di produzione.

4. Esempio di richiesta (curl)

curl -X POST https://idserver.pa.gov.it/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -d "grant_type=client_credentials" \
  -d "scope=anagrafica:lettura"

Il server risponde con un JSON contenente access_token, expires_in e eventuali campi aggiuntivi. Memorizza il token e la sua scadenza per evitare chiamate fallite.

Il formato della risposta: Access Token, Refresh Token e Time-to-Live (TTL)

Il formato della risposta: Access Token, Refresh Token e Time-to-Live (TTL)

Una volta completata l'autenticazione, l'endpoint di autorizzazione OAuth 2.0 restituisce una risposta JSON. La struttura è standard, ma i dettagli implementativi possono variare a seconda delle specifiche dell'API della Pubblica Amministrazione. Ecco i componenti principali della risposta:

• Access Token: È la credenziale effimera che il client usa per accedere alle risorse protette (l'API della PA). Viene inviato nell'header HTTP Authorization: Bearer <token>. Non controllarlo direttamente: devi memorizzarlo in modo sicuro (es. in memoria volatile) e trasmetterlo con ogni richiesta.
• Refresh Token: Una stringa crittografata che permette di ottenere un nuovo Access Token senza richiedere nuovamente le credenziali all'utente. Usalo per mantenere la sessione attiva durante l'uso prolungato dell'applicazione. Conservalo in un archivio cifrato, poiché la sua compromissione permetterebbe l'accesso non autorizzato.
• Time-to-Live (TTL): Indicato nei campi expires_in (secondi) e refresh_token_expires_in. Definisce la validità dei token. Per sicurezza, implementa una logica di rinnovo proattivo: programmare il refresh almeno 5 minuti prima della scadenza dell'Access Token per evitare interruzioni di servizio.

Ecco un esempio di payload JSON atteso:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def502001234567890abcdef...",
  "refresh_token_expires_in": 86400,
  "scope": "api_pa_read api_pa_write"
}

Gestione degli errori comuni (invalid_grant, invalid_request)

Uno degli ostacoli più comuni nell'implementazione OAuth 2.0 per l'integrazione API PA riguarda la gestione degli errori standard del protocollo. Analizziamo i due errori più frequenti: invalid_grant e invalid_request.

Invalid Request (Errore 400)

Questo errore si verifica quando la richiesta presenta parametri mancanti, duplicati o con formato non valido. Controlla sempre la correttezza dei parametri obbligatori come client_id, redirect_uri e scope. Verifica inoltre che la code challenge PKCE sia generata correttamente secondo lo standard RFC 7636.

Invalid Grant (Errore 400)

Questo errore indica che il codice di autorizzazione o il refresh token sono scaduti, revocati o già utilizzati. Assicurati che il codice venga scambiato per l'access token entro 10 minuti dalla generazione e che i token non vengano riutilizzati. Per le PA, verifica anche la validità del certificato di firma digitale.

Entrambi gli errori richiedono un log dettagliato e una risposta coerente verso l'utente finale.

Step 3: Chiamata alle API PA (Accesso alle Risorse)

Con il token di accesso in possesso, è ora possibile effettuare le chiamate effettive alle API della Pubblica Amministrazione (API PA). Questa fase rappresenta il cuore dell'intero processo di integrazione: è qui che l'applicazione richiede dati o esegue operazioni specifiche sulle risorse esposte dal sistema della PA, dimostrando l'autorizzazione ottenuta tramite OAuth 2.0.

Il meccanismo di autenticazione per ogni chiamata è semplice ma fondamentale: il token di accesso deve essere inserito nell'header HTTP della richiesta, utilizzando lo schema standard "Bearer". Senza questo header correttamente formato, la chiamata verrà respinta con un errore di autenticazione (solitamente HTTP 401 Unauthorized).

Struttura di una chiamata API con token Bearer

Ogni chiamata verso un endpoint delle API PA deve includere il seguente header di autorizzazione:

Authorization: Bearer [access_token]

Dove [access_token] è la stringa alfanumerica ricevuta nella fase precedente (vedi Step 2). È fondamentale notare lo spazio obbligatorio tra la parola "Bearer" e il token stesso.

La URL dell'endpoint dipende dall'ambiente specifico (produzione o collaudo) e dal servizio richiesto. Ad esempio, per accedere ai dati di una pratica amministrativa, l'endpoint potrebbe essere simile a:

https://api-pa.egov.it/v1/pratiche/{idPratica}

Esempio di implementazione in Python

import requests

token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
endpoint = "https://api-pa.egov.it/v1/dati-cittadino"
headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/json"
}

response = requests.get(endpoint, headers=headers)

if response.status_code == 200:
    dati = response.json()
    print("Dati recuperati correttamente:", dati)
else:
    print(f"Errore {response.status_code}: {response.text}")

Esempio di implementazione in Node.js

const axios = require('axios');

const token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";
const endpoint = "https://api-pa.egov.it/v1/dati-cittadino";

axios.get(endpoint, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
})
.then(response => {
    console.log("Dati recuperati correttamente:", response.data);
})
.catch(error => {
    console.error(`Errore ${error.response.status}: ${error.response.data}`);
});

Gestione della risposta

Le API PA seguono generalmente lo standard HTTP per i codici di stato:

• 200 OK: La richiesta ha avuto successo e i dati sono contenuti nel corpo della risposta.
• 201 Created: Una nuova risorsa è stata creata con successo (tipico per operazioni POST o PUT).
• 400 Bad Request: La richiesta è malformata (es. parametro mancante o non valido).
• 401 Unauthorized: Token assente, scaduto o non valido.
• 403 Forbidden: Il token è valido ma non ha i permessi necessari per quella specifica risorsa.
• 404 Not Found: La risorsa richiesta non esiste.
• 429 Too Many Requests: Superato il limite di chiamate (rate limiting).
• 500 Internal Server Error: Errore generico lato server della PA.

È buona norma implementare un meccanismo di retry esponenziale in caso di errori transitori (5xx o 429) e gestire sempre la lettura del corpo dell'errore per diagnosticare problemi specifici.

Casi d'uso comuni

Le API PA offrono una vasta gamma di funzionalità. Ecco alcuni esempi pratici di chiamate che potresti dover implementare:

• Recupero dati anagrafici: Per popolare moduli o verificare l'identità dell'utente.
• Consultazione pratiche: Per permettere ai cittadini di monitorare lo stato delle loro richieste (permessi, domande, ecc.).
• Invio documentazione: Caricamento di file allegati a una pratica esistente (richiede supporto per multipart/form-data).
• Pagamenti: Inizializzazione di transazioni PagoPA tramite API dedicate.

Per ogni tipologia di chiamata, è essenziale consultare la documentazione tecnica specifica del servizio PA in uso, poiché potrebbero esserci requisiti aggiuntivi sul formato dei dati (es. utilizzo di XML firmato digitalmente invece di JSON).

Un altro aspetto critico è la gestione delle espressioni regolari (regex) e la validazione dei campi. Le API PA spesso applicano controlli rigorosi sui formati (es. Codice Fiscale, PEC, date in formato ISO 8601). Implementare una validazione lato client prima della chiamata API può ridurre significativamente il numero di errori "400 Bad Request".

Infine, tieni presente che alcune API potrebbero richiedere l'uso di certificati digitali specifici (es. CNS, Smart Card) per la firma digitale di certi payload, specialmente in operazioni di trasmissione telematica obbligatoria. Verifica sempre la documentazione tecnica del fornitore del servizio.

Passo successivo: Automa e gestisci la validità del token. Una volta che hai imparato a fare chiamate sicure alle API PA, la gestione del ciclo di vita del token diventa cruciale per applicazioni che operano 24/7.

Autenticazione tramite Bearer Token nell'header HTTP

Quando invii una richiesta a un'API della Pubblica Amministrazione, devi includere il token di accesso (Bearer Token) nell'header HTTP della richiesta. Questo metodo è noto come autenticazione tramite Bearer Token ed è il cuore del flusso OAuth 2.0 una volta ottenuto il token.

Il token è una stringa alfanumerica lunga e opaca, che rappresenta le credenziali dell'utente o del sistema. Non è un semplice ID, ma una stringa cifrata che il server di autorizzazione rilascia al tuo client dopo la fase di autorizzazione.

Per inviare il token, devi aggiungere un header specifico alla tua richiesta API. L'header deve chiamarsi Authorization e il suo valore deve essere nella forma Bearer [TOKEN], dove [TOKEN] è la stringa ricevuta.

Ecco un esempio pratico di una chiamata API con cURL:

curl -X GET "https://api.pa.gov.it/v1/dati" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/json"

È fondamentale rispettare la sintassi esatta: la parola chiave "Bearer" deve essere seguita da uno spazio e poi dal token. Assicurati che il tuo client non aggiunga spazi extra o caratteri speciali. Inoltre, proteggi il token: non esporlo mai in URL (query parameters) o nei log del client, poiché è sensibile e potrebbe compromettere la sicurezza dell'intera integrazione.

Validazione dello Scope e gestione dei 403 Forbidden

Quando l'API restituisce un errore 403 Forbidden nella tua implementazione OAuth 2.0 per l'integrazione con la PA, il problema è quasi sempre legato allo scope. Questo errore indica che le credenziali sono corrette, ma l'accesso alla risorsa specifica non è autorizzato.

Per validare efficacemente lo scope e gestire i 403, segui questi passaggi operativi:

• Ispeziona il token: Decodifica il tuo Access Token (JWT) e verifica la presenza dello scope esatto richiesto dall'endpoint API. Spesso basta un carattere errato o un mancato.
• Verifica la richiesta: Controlla nell'header della richiesta HTTP se stai inviando correttamente Authorization: Bearer [token]. Assicurati che non ci siano spazi extra o caratteri non validi.
• Controlla il grant type: Se usi Client Credentials, lo scope deve essere esplicitamente richiesto nella chiamata al server di autenticazione. Se non lo fai, potresti ottenere un token senza gli scope necessari.
• Analizza la risposta 403: Molte API PA restituiscono un body JSON con il dettaglio dell'errore. Leggi attentamente il messaggio: potrebbe indicare se il problema è lo scope mancante o un permesso revocato.

Per diagnosticare in tempi brevi, simula la chiamata con Postman o curl isolando l'invio del token per escludere errori nel payload della richiesta.

Approfondimento: SPID e CIE come Identity Provider

Approfondimento: SPID e CIE come Identity Provider

Una delle domande più frequenti quando si progetta un'implementazione OAuth 2.0 per servizi destinati alla Pubblica Amministrazione è: come gestire l'autenticazione degli utenti in modo sicuro, conforme al Quadro Europeo dell'Identità Digitale (eIDAS) e in linea con le normative italiane? La risposta risiede nell'adozione di SPID (Sistema Pubblico di Identità Digitale) e CIE (Carta d'Identità Elettronica) come Identity Provider (IdP) affidabili. Non si tratta solo di una scelta tecnologica, ma di un requisito normativo per garantire l'accesso ai servizi digitali della PA.

SPID e CIE, infatti, non sono semplici sistemi di login, ma entità certificate che rilasciano credenziali di autenticazione forte. Per l'implementazione tecnica, ciò significa che la tua applicazione (il Relying Party o Client) non gestisce direttamente username e password dell'utente finale, ma delega l'autenticazione a questi provider. Questo approccio, noto come Federated Identity, riduce drasticamente l'esposizione al rischio di data breach per l'organizzazione, poiché la gestione delle credenziali e la validità dell'identità sono curate da soggetti terzi certificati.

Come funziona l'integrazione tecnica

Dal punto di vista dello sviluppatore, l'integrazione di SPID o CIE in un'applicazione che espone API RESTful segue lo standard OpenID Connect (OIDC), che si pone come uno strato superiore a OAuth 2.0. Mentre OAuth 2.0 si occupa dell'autorizzazione (l'accesso a risorse), OIDC si occupa dell'autenticazione (chi è l'utente).

Il flusso tecnico tipico utilizzato per le integrazioni PA è l'Authorization Code Flow with PKCE (Proof Key for Code Exchange), considerato il più sicuro per applicazioni server-side. Ecco i passaggi fondamentali:

1. Request di autenticazione: L'applicazione invia l'utente all'endpoint di autenticazione dell'IdP (SPID o CIE) includendo parametri come client_id, redirect_uri, response_type=code, scope (che include openid), e code_challenge (per PKCE).
2. Autenticazione Utente: L'utente viene reindirizzato alla pagina di login dell'IdP scelto (es. Aruba, Infocert, Poste Italiane per SPID) o al portale CIE. Qui inserisce le proprie credenziali (es. SPID con PIN e OTP, o CIE con PIN e lettura NFC).
3. Ritorno del Codice di Autorizzazione: Una volta autenticato con successo, l'IdP reindirizza l'utente alla redirect_uri specificata nell'applicazione, appendo il codice di autorizzazione all'URL.
4. Scambio del Codice per l'Access Token: L'applicazione server-side (back-end) cattura il codice e lo invia, insieme al code_verifier (generato nel primo step), all'endpoint di token dell'IdP.
5. Ricezione degli Token: L'IdP verifica la validità del codice e del verifier. Se tutto è corretto, restituisce un Access Token (JWT) e un ID Token (anch'esso JWT). L'ID Token contiene le informazioni sull'identità dell'utente (claims), come il Codice Fiscale, il nome, il cognome e l'email.
6. Chiamata alle API PA: L'applicazione utilizza l'Access Token come Bearer Token nell'header HTTP delle richieste verso le API della PA. Il servizio API valida il token (firma digitale e scadenza) e concede l'accesso alle risorse.

Il ruolo di AgID e delle specifiche tecniche

Non è possibile implementare SPID o CIE in autonomia senza seguire le regole tecniche definite da AgID (Agenzia per l'Italia Digitale). AgID pubblica e aggiorna regolarmente le specifiche tecniche e i Registri degli Operatori. Per SPID, è necessario registrarsi come Identity Provider o utilizzare un fornitore di servizi già registrato. Per quanto riguarda l'integrazione come Relying Party, l'applicazione deve rispettare i requisiti di sicurezza e di interoperabilità.

Una particolarità tecnica rilevante è la gestione dei Metadata. SPID utilizza standard come SAML 2.0 (più vecchio) e OIDC (più moderno). Sebbene SPID sia nato su SAML, l'adozione di OIDC è cresciuta notevolmente grazie alla sua semplicità e alla compatibilità con architetture moderne a microservizi. L'implementazione tecnica deve quindi supportare l'interpretazione dei token JWT, la verifica delle firme crittografiche (solitamente RSA o ECDSA) tramite le chiavi pubbliche fornite dagli endpoint di discovery dell'IdP, e la validazione dei claim standard (come sub, iss, aud).

Best practice per l'implementazione

Per garantire un'implementazione robusta e conforme, segui queste best practice:

• Utilizzo di librerie standard: Non implementare la crittografia o il parsing dei token JWT in modo manuale. Utilizza librerie consolidate per il linguaggio di programmazione scelto (es. oidc-client per .NET, Passport.js per Node.js, Spring Security per Java). Queste librerie gestiscono automaticamente la validazione dei token, la gestione dei refresh token e la protezione contro attacchi comuni.
• Gestione sicura dei secret: Il client_secret deve essere conservato in modo sicuro (es. tramite gestori di segreti come Azure Key Vault o HashiCorp Vault) e non mai esposto nel front-end.
• Logging e auditing: Implementa un sistema di logging che registri gli eventi di autenticazione (successi e fallimenti) senza mai memorizzare dati sensibili dell'utente o credenziali.
• Consent Management: Rispetta il consenso dell'utente. Prima di chiamare API che richiedono dati sensibili (come il Codice Fiscale), assicurati che l'utente abbia esplicitamente acconsentito alla condivisione dei dati (richiesta implicita nello scope profile o email).

Integrare SPID e CIE tramite OAuth 2.0 e OIDC non è solo un adempimento normativo, ma un passo fondamentale verso un'architettura digitale interoperabile e sicura. Per una consulenza tecnica specializzata sulla progettazione e implementazione delle tue API, contatta i nostri esperti di Culture Digitali Srl.

Come SPID si interfaccia con il tuo OAuth Client

Il flusso di autenticazione SPID via OAuth 2.0

Nel modello PA, SPID funziona come Identity Provider (IdP) certificato, mentre la tua applicazione agisce come Relying Party (RP) tramite un OAuth Client. L'interfaccia non è diretta ma segue lo standard OpenID Connect 1.0 (OIDC), un layer che sovrastizza OAuth 2.0 per gestire l'autenticazione. Il processo parte quando l'utente richiede l'accesso alla tua API.

Prima di tutto, devi configurare il tuo client sul Portale SPID della PA. Qui registri l'Authorization Endpoint e il Token Endpoint forniti dall'IdP (es. Identity Provider della PA). Importante: per le integrazioni PA, spesso si utilizza l'ambiente produzione o collaudo. La configurazione include l'indirizzo di redirect (callback URL), che deve corrispondere esattamente a quello dichiarato.

Il flusso tipico (Authorization Code Flow) segue questi passaggi logici, che devi implementare nel tuo OAuth Client:

1. Richiesta di autenticazione: Il tuo client reindirizza l'utente all'Authorization Endpoint dell'IdP SPID, inviando parametri come response_type=code, client_id, redirect_uri, scope=openid (e profile per dati utente), e uno stato casuale (state) per la sicurezza.
2. Autenticazione utente: L'utente viene gestito dall'IdP SPID (inserimento credenziali, eventuale 2FA). L'IdP verifica l'identità e il livello di assurance (es. L2, L3).
3. Authorization Code: L'IdP invia un codice temporaneo (code) al redirect_uri del tuo client, previo consenso dell'utente.
4. Scambio del codice: Il tuo backend server (mai il frontend) effettua una chiamata POST al Token Endpoint dell'IdP. Invia il code, il client_id, il client_secret (o una chiave privata JWT per il private_key_jwt) e il redirect_uri. L'endpoint verifica le credenziali e restituisce un Access Token e un ID Token JWT.
5. Verifica dell'ID Token: Il tuo client verifica la firma JWT dell'ID Token (usando le chiavi pubbliche dell'IdP, scaricate dal discovery endpoint) e i campi standard (iss, aud, exp) per garantire l'integrità e l'autenticità.
6. Accesso all'API: L'Access Token viene inviato nell'header Authorization: Bearer <token> per chiamare l'API PA protetta. L'API verifica il token tramite l'IdP o un introspection endpoint.

Per le API PA, controlla sempre la documentazione specifica (es. per l'IO Platform o altre API di interesse nazionale): potrebbero richiedere claim aggiuntivi (es. fiscal_number) o un DPoP (Demonstrative Proof-of-Possession) per binding del token al client. Gestisci gli errori OAuth standard (es. access_denied) e assicurati che il tuo client sia conforme alle linee guida AGID per la sicurezza (uso HTTPS, validazione redirect_uri, gestione segreta del client_secret).

Il profilo OpenID Connect (OIDC) sovrastante l'OAuth di SPID

Il profilo OpenID Connect (OIDC) sovrastante l'OAuth di SPID

Mentre OAuth 2.0 si occupa esclusivamente dell'autorizzazione (consentendo a un'applicazione di agire per conto dell'utente), la vera standardizzazione tecnica e semantica di SPID si basa sul profilo OpenID Connect (OIDC). OIDC è un protocollo di autenticazione costruito come uno strato sopra OAuth 2.0, essenziale per garantire che l'Identity Provider (IdP) e il Relying Party (RP, ovvero la tua applicazione) si scambino informazioni sull'utente in modo sicuro e interoperabile.

In ambito SPID, OIDC definisce tre componenti fondamentali che l'implementazione tecnica deve gestire rigorosamente:

• ID Token (JWT): È il cuore dell'autenticazione. Si tratta di un JSON Web Token firmato digitalmente dall'IdP. Contiene le claims (affermazioni) relative all'autenticazione dell'utente, come l'identificativo univoco (spid_code), l'issuer (l'IdP che ha emesso il token), l'audience (la tua applicazione) e il timestamp di scadenza. A differenza di un semplice token di accesso OAuth, l'ID Token garantisce chi è l'utente.
• Scope OpenID: Per avviare un flusso OIDC, la richiesta di autorizzazione OAuth 2.0 deve includere obbligatoriamente lo scope openid. Questo segnala all'IdP che la richiesta è di natura mista: autorizzazione e, soprattutto, autenticazione.
• UserInfo Endpoint: Dopo aver ottenuto l'ID Token, la tua applicazione può recuperare dati aggiuntivi sull'utente chiamando l'endpoint /userinfo. Qui è possibile richiedere i dati allo stato puro, come codice fiscale, nome, cognome e altri attributi SPID, ma solo presentando un access token valido.

La specifica SPID impone l'uso dell'Authentication Request (request_uri) e, in scenari avanzati, della JWT Secured Authorization Request (JAR) per firmare le richieste stesse, mitigando attacchi come il mix-up attack. Un corretto profiling OIDC garantisce non solo l'autenticazione, ma anche la gestione sicura dei consent e la rivocabilità dei token.

Sicurezza: Best Practices per le API PA

Implementare un'API per la Pubblica Amministrazione richiede un approccio alla sicurezza proattivo e strutturato. Non si tratta solo di rispettare un insieme di linee guida, ma di costruire un sistema difensivo in profondità che protegga sia l'infrastruttura digitale che i dati dei cittadini. La sicurezza non è un optional tecnico, ma un requisito normativo e una responsabilità istituzionale.

Dobbiamo partire da un presupposto: le API espongono funzionalità e dati. Se protette in modo inadeguato, diventano una porta d'accesso privilegiata per attacchi informatici. La Guida tecnica all'implementazione OAuth 2.0 per l'integrazione API PA definisce lo standard di autenticazione, ma la sicurezza si costruisce intorno a quel nucleo con misure aggiuntive che mitigano rischi specifici.

1. Principi fondamentali della sicurezza delle API PA

Prima di scendere nel dettaglio tecnico, è essenziale stabilire i principi guida. Per un'API destinata alla Pubblica Amministrazione, questi principi devono essere:

• Privacy by Design & Default: La protezione dei dati personali integrata nella progettazione, non aggiunta a posteriori.
• Zero Trust: Non fidarsi mai per implicito di nessuna richiesta, interna o esterna. Ogni accesso deve essere verificato.
• Minimo Privilegio: Ogni client (applicazione) deve avere solo i permessi strettamente necessari per funzionare.
• Trasparenza e Auditabilità: Ogni operazione deve essere tracciata per garantire rispondenza e tracciabilità.

2. Autenticazione e Autorizzazione: Oltre OAuth 2.0

OAuth 2.0 è il protocollo standard per l'autorizzazione, ma per le API PA l'autenticazione deve essere robusta.

2.1 Uso di TLS/HTTPS obbligatorio

La prima regola è la crittografia del canale. Tutte le comunicazioni tra client e server API devono avvenire esclusivamente tramite HTTPS (TLS 1.2 o superiore). Non ci sono eccezioni, nemmeno per test o ambienti di sviluppo. È necessario implementare un rigoroso controllo del certificato SSL/TLS per evitare attacchi Man-in-the-Middle (MITM).

2.2 Scope e Ruoli Definiti con Precisione

Nella configurazione OAuth 2.0, gli scope non sono semplici etichette, ma definiscono i confini di accesso. Per le API PA è fondamentale:

• Definire scope granulari (es. anagrafica_lettura, anagrafica_scrittura).
• Associare ogni scope a un profilo utente/ruolo specifico (cittadino, operatore PA, sistema esterno).
• Evitare scope generici come read o write su tutte le risorse.

Se utilizzi un provider di identità (IdP) come Google o Azure AD, assicurati di mappare correttamente i gruppi di Active Directory agli scope dell'API.

2.3 Token JWT e Validazione Strict

Il token di accesso (solitamente JWT - JSON Web Token) deve essere validato rigorosamente a ogni richiesta. I passaggi obbligatori sono:

• Firma: Verificare la firma digitale del token usando la chiave pubblica dell'issuer.
• Audience (aud): Controllare che il token sia destinato specificamente all'API in questione.
• Issuer (iss): Verificare che il token provenga dall'IdP fidato.
• Scadenza (exp/nbf): Controllare che il token non sia scaduto o non ancora valido.

3. Gestione delle Chiavi API e Secret

Le chiavi API (API Keys) sono spesso usate per l'autenticazione di sistemi server-to-server, ma rappresentano un punto debole se gestite male.

3.1 Conservazione Sicura

Le chiavi non devono mai essere hardcodate nel codice sorgente o esposte nel client-side (browser, app mobile). Utilizzare sistemi di gestione dei segreti (Secret Management) come:

• Azure Key Vault / AWS Secrets Manager.
• Environment variables (solo su server configurati correttamente).
• Configurazioni esterne protette da accessi RBAC (Role-Based Access Control).

3.2 Rotazione e Revoca

Implementare una policy di rotazione periodica delle chiavi (es. ogni 90 giorni). In caso di compromissione, deve esistere un meccanismo immediato di revoca e rigenerazione della chiave senza downtime del servizio.

4. Limitazione della Velocità (Rate Limiting) e Controllo del Carico

Le API PA sono bersagli comuni per attacchi DDoS (Distributed Denial of Service) o per tentativi di brute force sugli endpoint di autenticazione.

4.1 Rate Limiting a livello di Client

Impostare limiti di richieste per unità di tempo (es. 1000 richieste/ora per client) basati sugli scope e sul piano tariffario. Questo protegge l'infrastruttura e garantisce equità di accesso.

4.2 Request Throttling

In caso di picchi anomali, implementare meccanismi di throttling che rallentano le risposte invece di rifiutarle bruscamente, mantenendo il sistema responsivo.

5. Validazione Input e Sanificazione

Una delle vettori d'attacco più comuni è l'injection (SQL, NoSQL, Command). L'API deve validare ogni input ricevuto.

• Schema Validation: Usa JSON Schema per validare la struttura dei payload in entrata e in uscita.
• Sanificazione: Pulisci i dati per prevenire attacchi Cross-Site Scripting (XSS) se i dati vengono esposti in frontend.
• Limitazione della dimensione: Blocca richieste con payload eccessivamente grandi (es. > 5MB) per prevenire buffer overflow o DoS.

6. Logging, Monitoring e Alerting

La sicurezza è anche visibilità. Senza log, non c'è difesa forense.

6.1 Cosa loggare (e cosa no)

Logga eventi di sicurezza critici:

• Tutti gli accessi falliti (401, 403).
• Richieste superanti la soglia di Rate Limiting.
• Accessi con token scaduti o non validi.
• Cambiamenti di ruolo o scope.

Non loggare mai: Password, segreti, token completi, o dati personali sensibili (PII) in chiaro. I log devono essere anonimizzati o cifrati.

6.2 SIEM e Alerting in Tempo Reale

Inoltra i log a un sistema SIEM (Security Information and Event Management). Configura alert automatici per pattern sospetti, ad esempio:

• Accessi da IP geografici anomali.
• Tentativi di accesso multipli falliti per un singolo client.
• Utilizzo di scope privilegiati in orari non lavorativi.

7. Sicurezza nel Ciclo di Vita dello Sviluppo (SDLC)

La sicurezza non è solo operativa, ma deve essere integrata nello sviluppo (DevSecOps).

• Code Review: Ogni pull request deve includere una revisione della sicurezza.
• SAST/DAST: Eseguire scanner statici e dinamici sul codice e sulle API in esecuzione (es. SonarQube, OWASP ZAP).
• Dipendenze: Controllare continuamente le librerie di terze parti per vulnerabilità note (Software Composition Analysis).

8. Conformità Normativa (GDPR e GdP)

Per le API PA, la conformità al GDPR è vincolante. Le best practice includono:

• Minimizzazione dei dati: L'API deve restituire solo i dati strettamente necessari richiesti dallo scope.
• Diritto all'oblio: Implementare endpoint per la cancellazione dei dati se richiesto legalmente.
• DPIA: Valutare l'impatto sulla protezione dei dati per ogni nuova integrazione API.

Implementare queste best practices richiede competenze specifiche e un approccio strutturato. Non sottovalutare la sicurezza delle tue API: un singolo punto debole può compromettere l'intera infrastruttura.

Storage sicuro dei token: Database vs Memoria volatile

La scelta dello storage per i token è una decisione critica che impatta direttamente sulla sicurezza e sull'operatività dell'integrazione API PA. L'approccio più sicuro prevede l'utilizzo di un database cifrato per la persistenza dei refresh token, garantendone la durabilità tra le sessioni. I dati sensibili devono essere cifrati sia in transito (TLS) che a riposo (es. AES-256), con accesso tramite un gestore delle chiavi dedicato. Per ridurre il rischio, evita di memorizzare gli access token, che per natura sono a breve scadenza e possono essere ricalcolati.

Al contrario, l'uso della memoria volatile (es. Redis protetto o cache locale) è ideale per gli access token, che vengono scartati al termine della sessione. Questo approccio minimizza la superficie di attacco, poiché i dati sensibili non persistono su disco. Tuttavia, richiede una gestione rigida dei timeout e delle policy di cache. Una soluzione ibrida è spesso la migliore: storage persistente per i segnali di revoca e la memoria volatile per il traffico attivo. Le PA devono valutare il trade-off tra continuità operativa e sicurezza, allineandosi al GDPR e alle linee guida dell'Agenzia per l'Italia Digitale (AgID).

Validazione del parametro 'state' per prevenire CSRF

Un punto critico nella procedura di Implementazione OAuth 2.0 per l'integrazione API PA è la validazione del parametro state. Questo parametro, generato dal client, serve come 'nonce' (numero usato una sola volta) per proteggere da attacchi Cross-Site Request Forgery (CSRF). Durante il flusso OAuth, l'utente viene reindirizzato all'authorization server; senza il controllo dello stato, un attaccante potrebbe iniettare una sua richiesta di autorizzazione.

Per mitigare il rischio, il tuo sistema deve generare un valore univoco, imprevedibile e associato alla sessione dell'utente prima di inviare la richiesta di autorizzazione. Questo valore va conservato (es. in sessione o nel token JWT) e restituito dall'authorization server nella URL di redirect (callback).

Al ricevimento del callback, confronta il valore ricevuto con quello memorizzato: se corrispondono e la sessione è valida, prosegui con lo scambio del codice di autorizzazione per l'access token; altrimenti, interrompi l'operazione e segnala un errore di sicurezza.

Questa validazione è un passaggio obbligatorio per garantire che la risposta appartenga alla tua richiesta iniziale, proteggendo l'integrità del flusso di autenticazione.

HTTPS/TLS 1.2+: Un requisito non negoziabile

La sicurezza dei dati trasmessi tra il sistema dell'ente e le API della Pubblica Amministrazione (PA) è garantita dalla crittografia del canale di comunicazione. Per questo motivo, l'uso di HTTPS con protocollo TLS versione 1.2 o superiore (TLS 1.2+) è un requisito tecnico obbligatorio e non negoziabile, imposto da normative nazionali e dall'Architettura Generale per l'Interoperabilità dei Sistemi della PA (AGID).

Il protocollo TLS (Transport Layer Security) protegge la connessione in tre modi fondamentali: autentica il server (tramite certificati digitali), garantisce la riservatezza dei dati (tramite cifratura end-to-end) e ne assicura l'integrità (evitando alterazioni durante il trasporto). È fondamentale assicurarsi che il client invii le richieste esclusivamente su porte sicure (tipicamente la 443) e che sia configurato per accettare solo certificate emessi da Certificate Authority (CA) riconosciute.

Non utilizzare TLS 1.0 o 1.1: sono protocolli obsoleti e vulnerabili a exploit noti (come POODLE o BEAST). Durante la fase di configurazione, verifica che la tua piattaforma disabiliti l'accesso tramite protocolli insicuri e supporti solo versioni recenti del TLS. Un endpoint non crittografato sarà respinto immediatamente dai gateway di sicurezza della PA, bloccando ogni tentativo di integrazione.

Gestione del Ciclo di Vita dei Token e Refresh

Gestione del Ciclo di Vita dei Token e Refresh

Una delle sfide più critiche nell'integrazione con le API della Pubblica Amministrazione è gestire la validità temporanea dei token di accesso. OAuth 2.0 non prevede token eterni per motivi di sicurezza: un token di accesso ha una scadenza breve, tipicamente tra i 5 e i 60 minuti, per limitare i danni in caso di compromissione. Tuttavia, un'applicazione che deve operare in modo continuativo non può costringere l'utente a effettuare il login ogni volta che il token scade.

Ecco perché il Refresh Token entra in gioco. Quando un client richiede l'accesso all'API con un token scaduto, riceve un errore 401 Unauthorized. Invece di interrompere l'operazione, l'applicazione deve intercettare questo errore e utilizzare il refresh token per ottenere un nuovo access token senza bisogno di ri-autenticare l'utente. Questo processo deve essere trasparente e gestito automaticamente a livello di middleware o helper di rete.

Il flusso corretto di gestione del ciclo di vita prevede questi passaggi operativi:

1. Conservazione sicura: memorizza access token e refresh token in un secure storage (es. Keychain per iOS, Keystore per Android, o variabili di ambiente server-side protette). Non incollarli mai nel codice sorgente.
2. Rilevamento scadenza: l'applicazione deve controllare la scadenza del token prima di ogni chiamata API o, più efficientemente, basarsi sulla risposta 401 per innescare il refresh.
3. Richiesta di refresh: invia una POST al endpoint del token provider (es. /oauth/token) con grant_type=refresh_token, il client ID, il client secret e il refresh token stesso.
4. Rinnovo e sostituzione: se la richiesta va a buon fine, l'endpoint restituisce un nuovo access token (e talvolta un nuovo refresh token). Il sistema deve sostituire immediatamente quello vecchio con il nuovo.

È fondamentale implementare una strategia di retry intelligente. Se il refresh token è scaduto o invalidato, l'unica opzione è riportare l'utente alla schermata di login. Inoltre, è buona prassi implementare un meccanismo di backoff esponenziale in caso di errori temporanei del server durante il refresh, per non sovraccaricare i servizi della PA.

Quando e come usare il Refresh Token

Quando e come usare il Refresh Token

Il Refresh Token è fondamentale per garantire l'accesso continuo alle API della PA senza richiedere ripetutamente le credenziali all'utente, bilanciando sicurezza e user experience. Viene usato unicamente quando l'AccessToken è scaduto o invalidato. Il flusso è automatico e trasparente per l'utente finale.

Quando usarlo:

• Quando ricevi un errore 401 Unauthorized dalla API (token scaduto).
• Quando l'AccessToken è vicino alla sua scadenza (solitamente breve: 5-15 minuti).
• Mai in concomitanza con la prima autenticazione: in quel caso si usa solo la Authorization Code grant.

Come implementarlo (flusso tecnico):

1. Memorizzazione sicura: Salva il Refresh Token (e l'AccessToken) in un HttpOnly Secure Cookie o in un gestore di segrete come Azure Key Vault. Evita localStorage.
2. Intercettazione errore 401: Nel tuo middleware o client API, intercetta la risposta 401.
3. Richiesta nuovo token: Invia una richiesta POST all'endpoint di token della PA (/oauth2/token) con grant_type=refresh_token, il client_id, il client_secret e il Refresh Token corrente.
4. Aggiornamento e retry: Se la richiesta ha successo (200 OK), sostituisci il vecchio AccessToken con il nuovo (e conserva eventualmente il nuovo Refresh Token se viene ruotato). Riprova la chiamata API originale con il nuovo token.
5. Gestione fallimenti: Se il Refresh Token è scaduto o revocato (errore invalid_grant), reindirizza l'utente alla login o forza un nuovo flusso di autorizzazione.

Best practice: Implementa un meccanismo di "token refresh on-demand" (non pre-fetching) e assicurati che ogni richiesta di refresh sia idempotente per evitare race condition in scenari multi-thread o multi-device.

Implementazione della logica di retry e backoff esponenziale

Implementazione della logica di retry e backoff esponenziale

Le integrazioni con le API delle Pubbliche Amministrazioni sono soggette a transienti di rete e carichi variabili. Per garantire stabilità, implementare una strategia di retry con backoff esponenziale.

Il pattern prevede il reinvio della richiesta in caso di errori transitori (HTTP 429, 500, 502, 503, 504). La logica deve incrementare il tempo di attesa tra i tentativi in modo esponenziale (es. 1s, 2s, 4s, 8s) per evitare di sovraccaricare il server.

Regole chiave:

• Condizioni di retry: Applica il retry solo sugli errori transienti. Non riprovare su errori client (4xx, tranne 429) o su errori di autenticazione.
• Jitter: Introduci un ritardo casuale (jitter) al backoff per prevenire il "thundering herd" (picchi di traffico sincronizzati).
• Limiti: Imposta un numero massimo di tentativi (es. 3-5) e un timeout totale per evitare cicli infiniti.

Utilizzare librerie testate (come Resilience4j o Polly) è consigliato per gestire questi aspetti in modo robusto.

CTA Soft: Analisi Gratuita delle Tue Integrazione API
Vuoi verificare se la tua infrastruttura è pronta per le API PA? Richiedi subito un'analisi tecnica gratuita del tuo sistema di autenticazione e gestione degli errori.

Checklist di Implementazione e Debug

Checklist di Implementazione e Debug

Per garantire un'integrazione OAuth 2.0 robusta con le API della Pubblica Amministrazione, segui questa lista di controllo.

• Configurazione Client: Verifica che client_id, client_secret e l'URL di redirect siano correttamente registrati nel portale della PA (es. SPID/CIE).
• Endpoint Authorize: Costruisci l'URL con gli scopes corretti e verifica il parametro state per la protezione CSRF.
• Flusso Token: Controlla la validità del code ricevuto e scambia il codice per l'access token entro pochi secondi.
• Access Token: Utilizza HTTPS obbligatorio. Includi il token nell'header Authorization: Bearer <token> per ogni richiesta API.
• Refresh Token: Implementa la logica di rinnovo automatico del token prima della scadenza per evitare interruzioni.
• Debug: Logga gli errori (400, 401, 403) e verifica le JWKs fornite dalla PA per validare gli ID Token se utilizzati.

Stai implementando il gateway? Assicurati di gestire correttamente i CORS e le policy di sicurezza. Per una review tecnica richiedi una call con i nostri esperti.

Domande Frequenti (FAQ)

È possibile utilizzare OAuth 2.0 senza PKCE per le API PA?

No, secondo le linee guida AgID e le best practice RFC 7636, l'uso di PKCE (Proof Key for Code Exchange) è obbligatorio per applicazioni native e fortemente raccomandato per quelle web, specialmente quando il Client Secret non può essere memorizzato in modo sicuro (come nelle app mobile).

Quali sono gli scope tipici delle API PA?

Gli scope definiscono i permessi specifici. Possono variare a seconda dell'API (es. 'dati_anagrafici', 'reddito', 'situazione_ps'). La lista completa è disponibile nella documentazione tecnica specifica del servizio API che si intende integrare.

Cosa succede se l'utente nega il consenso durante il flusso SPID?

Se l'utente nega il consenso, l'Authorization Server reindirizza l'utente al 'redirect_uri' con un errore (tipicamente 'access_denied'). Il tuo sistema deve essere in grado di catturare e gestire questo errore per informare l'utente.

Quanto tempo dura un Access Token nelle API PA?

La durata dell'Access Token è definita dall'Identity Provider, ma è solitamente breve (da 5 a 15 minuti) per limitare i danni in caso di intercettazione. Il Refresh Token ha una durata maggiore (ore o giorni).

Contattaci

contattaci per saperne di più