Device Authorization Flow
Il Device Authorization Grant (RFC 8628) consente agli utenti di effettuare il login su dispositivi con capacità browser limitate o assenti. Invece di inserire le credenziali direttamente sul dispositivo, l’utente vede un codice breve e un URL. Visita l’URL da un telefono o laptop, inserisce il codice e approva la richiesta. Nel frattempo, il dispositivo fa polling sull’endpoint token finché l’utente completa l’autorizzazione.
Casi d’uso comuni:
- App per smart TV che mostrano un codice sullo schermo da approvare con il telefono
- Strumenti CLI che aprono un browser per l’autenticazione dell’utente
- Dispositivi IoT senza tastiera o schermo che stampano un codice sull’output seriale
- Terminali kiosk e POS
Come Funziona
Il device flow è un protocollo a due canali. Il dispositivo comunica con l’endpoint token, mentre l’utente interagisce con Auris tramite un browser su un dispositivo separato:
- Il dispositivo invia una richiesta token a
/api/oauth/device/codecon il suoclient_ide gli scope richiesti - Auris restituisce un
device_code(opaco, lungo), unouser_code(breve, leggibile dall’utente, 8 caratteri), unaverification_urie unintervaldi polling - Il dispositivo mostra lo
user_codee laverification_uriall’utente - L’utente visita l’URL di verifica in un browser, inserisce il codice e si autentica con Auris
- Nel frattempo, il dispositivo fa polling su
POST /api/auth/tokencongrant_type=urn:ietf:params:oauth:grant-type:device_codeall’intervallo specificato - Una volta che l’utente approva, il poll successivo restituisce un access token e un refresh token
- Se l’utente nega o il codice scade, il poll restituisce un errore
Configurazione nella Console
Abilita il Device Flow
Nella Console Auris, vai su Applicazioni e seleziona l’applicazione che userà il device flow. Nella scheda Impostazioni, attiva Abilita Device Flow.
Configura le Impostazioni
Imposta la durata del device code e l’intervallo di polling:
| Impostazione | Default | Note |
|---|---|---|
| Durata Codice | 600 secondi (10 minuti) | Tempo massimo che l’utente ha per inserire il codice e approvare |
| Intervallo Polling | 5 secondi | Intervallo minimo tra le richieste di polling del token dal dispositivo |
| Lunghezza User Code | 8 caratteri | Alfanumerico, maiuscolo, facile da leggere e digitare |
Nota il Client ID
Il device flow usa un client pubblico (nessun client secret). Copia il Client ID dalla scheda Credenziali.
Implementazione
JavaScript SDK
import { AurisClient } from '@auris/js'
const auris = new AurisClient({
domain: 'auth.tuodominio.com',
clientId: 'il-tuo-client-id-dispositivo',
})
// Passo 1: Richiedi un device code
const deviceAuth = await fetch('https://auth.tuodominio.com/api/oauth/device/code', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
client_id: 'il-tuo-client-id-dispositivo',
scope: 'openid profile email',
}),
}).then(r => r.json())
// Passo 2: Mostra all'utente
console.log(`Vai su: ${deviceAuth.verification_uri}`)
console.log(`Inserisci il codice: ${deviceAuth.user_code}`)
// Passo 3: Polling per il token
const token = await pollForToken(deviceAuth)
async function pollForToken(deviceAuth) {
const interval = deviceAuth.interval * 1000 // converti in ms
const expiresAt = Date.now() + deviceAuth.expires_in * 1000
while (Date.now() < expiresAt) {
await new Promise(resolve => setTimeout(resolve, interval))
const response = await fetch('https://auth.tuodominio.com/api/auth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
device_code: deviceAuth.device_code,
client_id: 'il-tuo-client-id-dispositivo',
}),
})
if (response.ok) {
return await response.json()
}
const error = await response.json()
if (error.error === 'authorization_pending') {
continue // l'utente non ha ancora approvato
}
if (error.error === 'slow_down') {
await new Promise(resolve => setTimeout(resolve, 5000)) // rallenta
continue
}
if (error.error === 'expired_token') {
throw new Error('Device code scaduto. Riavvia il flusso.')
}
if (error.error === 'access_denied') {
throw new Error('L\'utente ha negato la richiesta di autorizzazione.')
}
throw new Error(`Errore inatteso: ${error.error}`)
}
throw new Error('Device code scaduto.')
}Risposta al Device Code
Quando richiedi un device code, Auris restituisce i seguenti campi:
| Campo | Tipo | Descrizione |
|---|---|---|
device_code | string | Codice opaco usato dal dispositivo per il polling. Tieni segreto. |
user_code | string | Codice alfanumerico breve (8 caratteri) mostrato all’utente. |
verification_uri | string | URL che l’utente visita per inserire il codice. |
verification_uri_complete | string | URL con il codice già pre-compilato come query parameter. |
expires_in | number | Secondi fino alla scadenza del device code (default: 600). |
interval | number | Intervallo minimo di polling in secondi (default: 5). |
Gestione degli Errori
Durante la fase di polling, l’endpoint token restituisce codici di errore specifici per indicare lo stato corrente:
| Codice Errore | HTTP Status | Significato | Azione del Client |
|---|---|---|---|
authorization_pending | 400 | L’utente non ha ancora approvato la richiesta | Continua il polling all’intervallo specificato |
slow_down | 428 | Polling troppo frequente | Aumenta l’intervallo di polling di 5 secondi |
expired_token | 400 | Il device code è scaduto | Riavvia il flusso dal passo 1 |
access_denied | 400 | L’utente ha esplicitamente negato la richiesta | Mostra un messaggio di errore, non riprovare |
Rispetta sempre il valore interval e l’errore slow_down. I client che fanno polling troppo aggressivamente riceveranno risposte HTTP 428 e il loro intervallo di polling verrà aumentato forzatamente. Violazioni ripetute possono causare la revoca del device code.
Pagina di Verifica Utente
Auris fornisce una pagina di verifica ospitata su /hosted/device dove gli utenti inseriscono il loro device code. La pagina:
- Chiede all’utente di inserire il codice a 8 caratteri
- Autentica l’utente (login richiesto se non c’è sessione attiva)
- Mostra il nome dell’applicazione richiedente e gli scope richiesti
- Chiede all’utente di approvare o negare la richiesta
- Mostra un messaggio di conferma in caso di successo
Se viene usato l’URL verification_uri_complete, il campo del codice è pre-compilato, risparmiando un passaggio all’utente.
Considerazioni sulla Sicurezza
- Breve durata del codice: I device code scadono dopo 600 secondi di default. Questo limita la finestra per l’intercettazione del codice.
- Codici leggibili dall’utente: I codici utente a 8 caratteri usano un set di caratteri non ambiguo (no
0/O,1/I/l). - Polling con rate limit: L’endpoint token impone l’intervallo di polling. I client che fanno polling troppo velocemente ricevono errori
slow_down. - Nessun client secret: Il device flow usa client pubblici perché il dispositivo non può memorizzare un secret in modo sicuro. Gli scope dovrebbero essere limitati di conseguenza.
- Monouso: Ogni device code può essere approvato solo una volta. Dopo l’emissione del token, il codice viene invalidato.
Poiché il device flow usa client pubblici, gli access token emessi hanno tipicamente una durata più breve rispetto ai flussi con client confidenziali. Considera l’uso dei refresh token per mantenere sessioni lunghe senza dover rieseguire il device flow.
Endpoint API
/api/oauth/device/codeRichiede un nuovo device code. Richiede client_id e facoltativamente scope nel corpo della richiesta. Restituisce device_code, user_code, verification_uri, expires_in e interval.
/api/auth/tokenEndpoint token. Per il device flow, imposta grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code e client_id. Restituisce l’access token in caso di successo, o un codice di errore durante il polling.
/api/oauth/device/verifyPagina di verifica ospitata. Accetta il query parameter opzionale user_code per la pre-compilazione.
/api/oauth/device/codesRequires: manage:device_codesElenca i device code attivi per il tenant. Endpoint admin per monitoraggio e debug.
Permessi Richiesti
| Operazione | Permesso |
|---|---|
| Abilita Device Flow su un’applicazione | manage:applications |
| Elenca device code attivi | manage:device_codes |
| Revoca un device code | manage:device_codes |
| Richiedi/polling per il token | Nessun permesso richiesto (endpoint pubblico) |
Guide Correlate
- Login Ospitato (PKCE) — Autenticazione interattiva browser-based
- Client Credentials M2M — Autenticazione server-to-server senza utente
- CIBA (Backchannel Auth) — Autenticazione disaccoppiata su dispositivo separato