OAuth2 / OIDC — collegare un servizio a Omniscol

Ciò che fa Omniscol come server OAuth2

Un servizio esterno — un agente IA, un connettore, una dashboard — diventa un client dichiarato nel Suo account; un utente della scuola approva il suo accesso tramite una schermata di consenso; il servizio riceve allora un token di accesso a breve durata, il cui perimetro è limitato agli scope concessi e ai diritti dell'utente.

Questo meccanismo è distinto dal SSO utente descritto in OIDC / SSO, dove Omniscol è al contrario client del Suo provider di identità per connettere i Suoi utenti. Qui, Omniscol è dal lato server: sono i servizi che si connettono a lui.

Due integrazioni Omniscol consumano questo server:

• MCP — l'autenticazione standard di un agente IA passa da questo server OAuth2 (vedi MCP — collegare un agente IA esterno);
• OneRoster — il produttore OneRoster si autentica tramite un token OAuth2 da macchina a macchina emesso da questo stesso server (vedi OneRoster).

Qualsiasi altro servizio conforme a OAuth2 / OIDC può connettersi allo stesso modo.

Discovery e endpoint del protocollo

Omniscol pubblica i suoi metadati di discovery agli indirizzi standard .well-known, serviti alla radice del dominio del Suo account (per esempio https://vostra-scuola.omniscol.com). Un client conforme vi trova da solo tutti gli endpoint, senza configurazione manuale:

• /.well-known/oauth-authorization-server — metadati del server di autorizzazione (RFC 8414);
• /.well-known/openid-configuration — metadati OpenID Connect (contenuto identico al precedente);
• /.well-known/jwks.json — chiavi pubbliche di verifica (JWKS), che permettono di verificare la firma degli id_token;
• /.well-known/oauth-protected-resource — metadati di risorsa protetta (RFC 9728).

Questi metadati annunciano gli endpoint del protocollo:

• /oauth/authorize — richiesta di autorizzazione (schermata di connessione poi di consenso);
• /oauth/token — scambio del codice contro un token, e rinnovo;
• /oauth/register — registrazione dinamica dei client (RFC 7591);
• /oidc/userinfo — informazioni sull'utente connesso (OIDC);
• /oauth/revoke — revoca di un token (RFC 7009).

Questi endpoint del protocollo sono pubblici: non sono riservati agli account Premium e non devono essere aperti manualmente. Solo la schermata di gestione dei client descritta più sotto rientra nel Premium.

I flussi di autorizzazione

Omniscol gestisce tre flussi OAuth2:

• Authorization code con PKCE — il flusso predefinito per un servizio che agisce per conto di un utente. Il servizio reindirizza l'utente verso /oauth/authorize; dopo la connessione e il consenso, Omniscol restituisce un codice di autorizzazione (valido 5 minuti) che il servizio scambia su /oauth/token. Il metodo PKCE adottato è S256, e il solo response_type accettato è code.
• Rinnovo (refresh_token) — per prolungare un accesso delegato senza ripassare dal consenso.
• Client credentials — flusso da macchina a macchina, senza utente, usato in particolare dai consumatori OneRoster. Il client si autentica direttamente e riceve un token di accesso.

Allo scambio, il server emette un token di accesso (Bearer, valido 1 ora) e, per i flussi utente, un token di rinnovo (valido 30 giorni). Quando lo scope openid è richiesto, un id_token OIDC firmato è emesso anch'esso; la sua firma si verifica tramite /.well-known/jwks.json. Il flusso client_credentials emette solo un token di accesso, senza rinnovo né id_token.

Il token di accesso si presenta poi nell'intestazione HTTP Authorization: Bearer <token>. A ogni chiamata, Omniscol verifica la sua firma, controlla che il client sia sempre attivo, che l'utente esista ancora e possieda il ruolo richiesto, e che gli scope del token coprano bene l'endpoint chiamato — in caso contrario la chiamata è rifiutata.

Gli scope e il consenso

Gli scope che gestisce su un client sono:

• read:basic — lettura degli orari, delle dashboard e delle consultazioni (moduli Pagina Iniziale, Orario, Dashboard, Gestione degli orari);
• read:user — lettura della lista degli utenti;
• write:data — scrittura su questi stessi moduli di consultazione;
• admin — accesso di amministrazione (moduli Amministrazione, Gestione delle assenze, Gestione degli orari).

Il server conosce anche gli scope OIDC (openid, email, profile) e gli scope OneRoster in sola lettura (prefisso imsglobal.org). Questi ultimi sono privilegiati: un client non può auto-attribuirseli tramite la registrazione dinamica; devono essere provisionati da un amministratore sulla scheda del client.

Lo scope effettivamente concesso è l'intersezione di ciò che il client richiede e di ciò che gli è registrato: un client non ottiene mai più di quanto figura sulla sua scheda. Durante il flusso utente, la schermata di consenso (/oauth/consent) mostra il nome e il logo del servizio richiedente nonché la lista leggibile degli scope richiesti, con i pulsanti Accetta e Rifiuta. Approvare emette il codice di autorizzazione e rimanda l'utente verso il servizio; rifiutare lo rimanda con un errore access_denied.

La registrazione dinamica dei client

L'endpoint /oauth/register implementa la registrazione dinamica (Dynamic Client Registration, RFC 7591): un servizio conforme può dichiararsi da solo come client, senza intervento manuale preliminare. È ciò che permette a un agente MCP di configurarsi a partire dal solo URL del server.

La registrazione dinamica non può attribuirsi uno scope privilegiato (gli scope OneRoster): questi sono silenziosamente scartati, e se nessuno scope valido sussiste, read:basic è concesso per impostazione predefinita. Gli scope privilegiati restano riservati a un provisioning da parte di un amministratore.

La schermata di gestione dei client OAuth2

Sugli account Premium, amministra i client da Amministrazione → Importare/Esportare, sezione OAuth2, con il pulsante OAuth2. L'accesso richiede prima la password amministratore — una conferma supplementare prima di aprire la schermata.

La schermata elenca i client registrati e, per ciascuno, mostra il suo stato (attivo / inattivo), il suo nome, i suoi scope, i suoi contatti e i suoi URI (sito, logo, URI di reindirizzamento). Può:

• Registrare un client — inserisca il nome, un software_id facoltativo, gli scope, i contatti, il sito, il logo e gli URI di reindirizzamento. Alla creazione, Omniscol mostra una sola volta il client_id e il client_secret.
• Modificare un client — solo campi sicuri sono modificabili: nome, scope, contatti, sito e logo. Gli URI di reindirizzamento, il software_id e il segreto non si modificano qui.
• Attivare o disattivare un client — un client disattivato vede i suoi token rifiutati dalla chiamata successiva.
• Eliminare un client — l'eliminazione è definitiva.

Il segreto del client

Il client_secret è mostrato una sola volta, alla registrazione. Omniscol conserva accanto ad esso solo un'impronta del segreto, mai il segreto in chiaro: non può essere ri-mostrato né recuperato in seguito. Lo copi immediatamente in un gestore di segreti.

Il client_id, invece, è deterministico: deriva dal nome dell'account, dal nome del client e da un'impronta dei suoi metadati tecnici. Due registrazioni strettamente identiche ricadono così sullo stesso identificativo.

Rinnovare il segreto (rotazione)

La rotazione del segreto esiste: emette un nuovo segreto, ne conserva solo la nuova impronta, e restituisce questo nuovo segreto una sola volta. Si effettua tramite l'endpoint di gestione della registrazione dinamica (/oauth/register/<client_id>/rotation) e presuppone di presentare il token di registrazione consegnato al client al momento della sua registrazione dinamica. Non è quindi attivata dalla schermata di gestione qui sopra, che non manipola questo token.

OAuth2 o chiave API: quale scegliere

Omniscol propone due meccanismi di accesso da macchina, con modelli di fiducia differenti:

• OAuth2 (questa pagina) — un terzo registrato ottiene, dopo il consenso di un utente, un token a durata di vita breve (1 h), limitato agli scope concessi, rinnovabile e revocabile (disattivando il client). Il flusso client_credentials copre inoltre la macchina a macchina senza utente. È la modalità adatta a un servizio terzo identificato, a MCP e a OneRoster.
• Chiave API (vedi API Omniscol) — un token autonomo firmato dal server, che integra una lista di endpoint autorizzati e che consegna Lei stesso al sistema esterno: nessun terzo registrato, nessuna schermata di consenso, nessun rinnovo. È una delega, da parte dell'amministratore, dei propri diritti a un sistema che controlla.

In sintesi: la chiave API è adatta quando consegna Lei stesso un accesso a un sistema che controlla; OAuth2 è adatto quando un servizio terzo identificato deve ottenere un accesso delegato, con scope e revocabile, o quando il protocollo lo impone (MCP, OneRoster).