OAuth 2.0 & OpenID Connect

Comprendere OAuth 2.0 e OpenID Connect è fondamentale per integrare correttamente con Auris. Questa pagina spiega i protocolli, le loro differenze, i grant type supportati da Auris e come Auris li implementa internamente.

Cos’è OAuth 2.0?

OAuth 2.0 (RFC 6749) è un framework di autorizzazione. Fornisce un modo standard per un utente di concedere a un’applicazione di terze parti un accesso limitato alle proprie risorse su un altro servizio, senza esporre le proprie credenziali all’applicazione di terze parti.

L’intuizione chiave è che OAuth 2.0 riguarda la delega dell’accesso — non la verifica dell’identità. Quando accedi a un’app di terze parti usando “Accedi con Google,” Google sta usando OAuth 2.0 per concedere all’app l’accesso ai tuoi dati del profilo, non per dimostrare che sei chi dici di essere. Quello è uno strato separato.

Ruoli Principali in OAuth 2.0

In Auris, l’Authorization Server e il Resource Server fanno parte della stessa piattaforma. Il Client è la tua applicazione e il Resource Owner è il tuo utente.

Cosa OAuth 2.0 Non È

OAuth 2.0 non:

• Definisce come un utente prova la propria identità (nessun protocollo di login)
• Specifica cosa c’è in un token di accesso
• Definisce come i token vengono validati dai resource server

Queste lacune hanno portato alla creazione di OpenID Connect.

Cos’è OpenID Connect?

OpenID Connect (OIDC) è un layer di autenticazione costruito sopra OAuth 2.0. Risponde alla domanda che OAuth 2.0 lascia senza risposta: “Chi è questo utente?”

OIDC estende il flusso Authorization Code di OAuth 2.0 introducendo:

1. L’ID Token — un JWT firmato contenente l’identità dell’utente (ID utente, email, nome, ecc.)
2. L’Endpoint UserInfo — dove il client può recuperare claim utente aggiuntivi
3. Claim Standardizzati — un insieme definito di nomi di claim (sub, email, name, picture, ecc.)
4. Documento Discovery — un URL noto che descrive gli endpoint del provider

Quando usi OIDC, richiedi lo scope openid in aggiunta a qualsiasi altro scope. La presenza di openid nello scope dice all’authorization server di emettere un ID Token insieme al token di accesso.

La Differenza in Pratica

In Auris, ogni flusso di login hosted è OIDC — lo scope openid è incluso per default e la risposta token contiene sempre un ID token in aggiunta ai token di accesso e refresh.

Grant Type Supportati da Auris

OAuth 2.0 definisce diversi “grant type” — flussi per ottenere token a seconda del tipo di client e del caso d’uso.

1. Authorization Code + PKCE (Consigliato)

Il flusso standard per le applicazioni user-facing (app web, app mobili, SPA, CLI con redirect browser). PKCE (Proof Key for Code Exchange, RFC 7636) viene aggiunto per proteggere dagli attacchi di intercettazione del codice.

Quando usarlo: Qualsiasi applicazione in cui un utente reale accede in modo interattivo.

Riepilogo del flusso:

1. L’app genera un code verifier e un code challenge
2. Il browser viene reindirizzato alla pagina di login hosted di Auris con il code challenge
3. L’utente si autentica
4. Auris reindirizza all’app con un authorization code
5. L’app scambia il codice + code verifier per i token

Vedi la pagina Flusso PKCE per una guida completa passo-passo.

2. Client Credentials (M2M)

Usato per la comunicazione machine-to-machine in cui non è coinvolto alcun utente. Un servizio si autentica usando il proprio client_id e client_secret per ottenere un token di accesso con scope definiti dal server.

Quando usarlo: Servizi backend, job pianificati, pipeline CI/CD, microservizi interni.

curl -X POST https://api.altovar.net/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "m2m-service-id",
    "client_secret": "m2m-service-secret",
    "scope": "read:users manage:roles"
  }'

Il token di accesso risultante ha "type": "m2m" nel suo payload e porta solo gli scope dichiarati — nessuna identità utente.

3. Device Authorization Grant (RFC 8628)

Per dispositivi che non possono aprire direttamente un browser: smart TV, strumenti CLI, dispositivi IoT, console di gioco.

Quando usarlo: Dispositivi con input limitato o strumenti CLI che non possono reindirizzare il browser dell’utente.

Riepilogo del flusso:

1. Il dispositivo richiede ad Auris un device code e un user code
2. Auris restituisce device_code, user_code e verification_url
3. Il dispositivo mostra lo user_code e chiede all’utente di andare al verification_url su un altro dispositivo
4. L’utente si autentica sul proprio telefono o computer e approva il dispositivo
5. Il dispositivo esegue il polling dell’endpoint token finché l’utente approva
6. L’endpoint token restituisce i token una volta approvato

4. Token Exchange (RFC 8693)

Permette di scambiare un token con un altro — usato per scenari di impersonificazione e delega in architetture multi-servizio complesse.

Quando usarlo: Servizi backend che devono agire per conto di un utente, o strumenti admin che devono impersonificare un utente per il debug.

5. CIBA (Client-Initiated Backchannel Authentication)

Un’estensione OpenID Connect che consente a un client di avviare l’autenticazione per un utente senza un redirect browser. Invece, l’utente riceve una notifica push o un messaggio out-of-band e approva o rifiuta la richiesta di autenticazione.

Quando usarlo: Autenticazione nei call center, approvazioni IoT, flussi ad alta garanzia dove vuoi autenticare l’utente su un dispositivo fidato separato.

Auris supporta CIBA nelle modalità poll, ping e push.

Endpoint OAuth 2.0 in Auris

Scope in Auris

Gli scope OAuth 2.0 sono stringhe separate da spazi che definiscono quale accesso concede un token.

Scope OIDC Standard

Scope M2M

I token M2M usano scope personalizzati definiti per applicazione nella Console. Esempi:

• read:users — accesso in sola lettura ai dati utente
• manage:roles — CRUD completo sui ruoli
• read:audit-logs — accesso all’API del log di audit

Come Auris Implementa OAuth 2.0

Auris è costruito su Keycloak come engine di identità sottostante, con Auris che estende e avvolge la funzionalità di Keycloak.

Keycloak come Engine Base

Keycloak gestisce:

• Archiviazione e verifica delle credenziali utente
• Gestione delle sessioni e emissione dei token
• Federazione SAML e OIDC
• Ponti per protocolli di login social

Estensioni Auris su Keycloak

Auris aggiunge sopra Keycloak:

• Pagine di Login Hosted: UI di login completamente branded, dominio personalizzato
• Actions Engine: Hook di codice lato server personalizzato che viene eseguito durante login, registrazione e emissione token
• Custom JWT Claims: Iniezione di claim configurabile per applicazione al momento dell’emissione token
• PKCE Enforcement: Applicato al layer Auris (non opzionale)
• MFA Adattivo: Scoring del rischio e autenticazione step-up basata su IP, dispositivo e comportamento
• Integrazione FGA: Controlli di autorizzazione fine-grained a livello di risorsa

Concetti Correlati

• I Token Spiegati — Token di accesso, refresh token e ID token in dettaglio
• Flusso PKCE — Flusso Authorization Code con Proof Key for Code Exchange
• Hosted Login (Universal Login) — Come Auris implementa OAuth2 tramite pagine hosted
• Guida Hosted Login — Integrazione PKCE passo-passo
• Credenziali M2M — Flusso OAuth2 server-to-server