SSO con App IO

io-sso è l'identity broker tra App IO e la Stanza del Cittadino che consente ai cittadini di accedere ai documenti direttamente da un messaggio App IO, senza dover effettuare un login manuale.

io-sso è un componente server-side che funge da identity broker tra App IO (PagoPA) e la Stanza del Cittadino (SDC). Permette a un cittadino di aprire un documento direttamente da un messaggio App IO senza dover fare login manuale sul portale.

Il componente usa NextAuth v5 con sessioni JWT e il provider FIMS (OIDC di PagoPA). Tutta la logica gira server-side: nessun componente client, nessuna variabile d'ambiente sensibile nel bundle browser. I cookie di sessione sono HttpOnly, Secure, SameSite=lax.

Multi-tenant

Ogni comune ha un proprio slug nell'URL. La configurazione del backend documentale (URL, credenziali operatore) è in SDC_TENANTS server-side — mai esposta al client.

https://appio-sso.opencityitalia.it/{tenant}/{sistema}/documents

Il problema: due client, due cookie jar

App IO usa due client separati: il client nativo (Ktor/Alamofire), che gestisce l'autenticazione FIMS in background, e Chrome Custom Tab, che apre il documento. Il problema è che le sessioni del client nativo non sono accessibili da Chrome: i due client hanno cookie jar separati.

La soluzione è un claim store in-memory (OTT — One Time Token): il JWT di sessione viene conservato server-side, indicizzato da un UUID con TTL di 60 secondi. Chrome lo consuma in un'unica operazione, dopodiché il claim viene eliminato.

Flusso di autenticazione

Vediamo il flusso completo dal click sulla CTA alla visualizzazione del documento:

Accesso ai documenti

I documenti SDC sono protetti da credenziali operatore. Quando il cittadino arriva sulla pagina del documento con una sessione valida, il server recupera il codice fiscale dal JWT, ottiene l'ID utente SDC tramite /api/users?cf=<codice_fiscale> e verifica che l'utente sia il proprietario del documento (owner) oppure sia presente in readers_allowed. Se il controllo è superato, il server funge da proxy verso SDC usando un token operatore in cache e restituisce il documento.

Formato URL della CTA

L'URL da inserire nella CTA del messaggio App IO segue questo schema:

iosso://https://appio-sso.opencityitalia.it/{tenant}/{sistema}/documents

Ad esempio, per il comune di Trento con il sistema IMIS:

iosso://https://appio-sso.opencityitalia.it/trento/imis/documents