Skip to Content

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:

  1. Il dispositivo invia una richiesta token a /api/oauth/device/code con il suo client_id e gli scope richiesti
  2. Auris restituisce un device_code (opaco, lungo), uno user_code (breve, leggibile dall’utente, 8 caratteri), una verification_uri e un interval di polling
  3. Il dispositivo mostra lo user_code e la verification_uri all’utente
  4. L’utente visita l’URL di verifica in un browser, inserisce il codice e si autentica con Auris
  5. Nel frattempo, il dispositivo fa polling su POST /api/auth/token con grant_type=urn:ietf:params:oauth:grant-type:device_code all’intervallo specificato
  6. Una volta che l’utente approva, il poll successivo restituisce un access token e un refresh token
  7. 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:

ImpostazioneDefaultNote
Durata Codice600 secondi (10 minuti)Tempo massimo che l’utente ha per inserire il codice e approvare
Intervallo Polling5 secondiIntervallo minimo tra le richieste di polling del token dal dispositivo
Lunghezza User Code8 caratteriAlfanumerico, 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

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:

CampoTipoDescrizione
device_codestringCodice opaco usato dal dispositivo per il polling. Tieni segreto.
user_codestringCodice alfanumerico breve (8 caratteri) mostrato all’utente.
verification_uristringURL che l’utente visita per inserire il codice.
verification_uri_completestringURL con il codice già pre-compilato come query parameter.
expires_innumberSecondi fino alla scadenza del device code (default: 600).
intervalnumberIntervallo 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 ErroreHTTP StatusSignificatoAzione del Client
authorization_pending400L’utente non ha ancora approvato la richiestaContinua il polling all’intervallo specificato
slow_down428Polling troppo frequenteAumenta l’intervallo di polling di 5 secondi
expired_token400Il device code è scadutoRiavvia il flusso dal passo 1
access_denied400L’utente ha esplicitamente negato la richiestaMostra 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:

  1. Chiede all’utente di inserire il codice a 8 caratteri
  2. Autentica l’utente (login richiesto se non c’è sessione attiva)
  3. Mostra il nome dell’applicazione richiedente e gli scope richiesti
  4. Chiede all’utente di approvare o negare la richiesta
  5. 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

POST/api/oauth/device/code

Richiede 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.

POST/api/auth/token

Endpoint 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.

GET/api/oauth/device/verify

Pagina di verifica ospitata. Accetta il query parameter opzionale user_code per la pre-compilazione.

GET/api/oauth/device/codesRequires: manage:device_codes

Elenca i device code attivi per il tenant. Endpoint admin per monitoraggio e debug.


Permessi Richiesti

OperazionePermesso
Abilita Device Flow su un’applicazionemanage:applications
Elenca device code attivimanage:device_codes
Revoca un device codemanage:device_codes
Richiedi/polling per il tokenNessun permesso richiesto (endpoint pubblico)

Guide Correlate