Vai al contenuto
Usher IdentityUsher Identity
Documentazione · TV e strumenti da riga di comando

TV, console e strumenti da riga di comando

Una TV non può mostrare facilmente una pagina di accesso, e uno strumento da riga di comando non dovrebbe chiedere una password. Con il device flow, il dispositivo mostra un breve codice e la persona lo inserisce nella Lobby del suo ambiente dal telefono o dal computer, dove ha già eseguito l’accesso.

Registra l’app

In Usher Console, apri l’ambiente, poi Applicazioni → Nuova applicazione → TV o riga di comando. L’app riceve un client ID e nessun segreto: un dispositivo non è in grado di custodirlo.

Il flusso

Terminale
# 1. the device asks for a code
curl -s -X POST https://acme.usherid.com/api/auth/device/code \
  -d client_id=YOUR_CLIENT_ID -d scope='openid email offline_access'
# → { "device_code": "…", "user_code": "6L95PBQQ",
#     "verification_uri": "https://acme.usherid.com/device",
#     "verification_uri_complete": "https://acme.usherid.com/device?user_code=6L95PBQQ",
#     "expires_in": 600, "interval": 5 }

# 2. it shows the code (and a QR code of verification_uri_complete), then polls
curl -s -X POST https://acme.usherid.com/api/auth/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=… -d client_id=YOUR_CLIENT_ID
# → { "error": "authorization_pending" } until the person allows it,
#   then { "access_token": "…", "id_token": "…", "refresh_token": "…" }
  • Interroga con garbo. Attendi interval secondi tra un’interrogazione e l’altra. Se interroghi più spesso, la risposta è slow_down.
  • Fermati quando te lo dicono. access_denied significa che la persona ha rifiutato; expired_token significa che sono passati dieci minuti. Richiedi un nuovo codice.
  • Mostra anche l’indirizzo. Non tutti possono inquadrare un codice QR: mostra verification_uri e il codice, spaziato come 6L95-PBQQ.

Su /device, la Lobby mostra alla persona quale app sta facendo la richiesta e per cosa. Le dice di proseguire solo se è stata lei ad avviarla e se il suo dispositivo mostra lo stesso codice.

Vincola i token al dispositivo (DPoP)

Un token copiato da un dispositivo resta un token. Con DPoP (RFC 9449), il dispositivo custodisce una chiave privata e invia una nuova prova firmata a ogni richiesta. Un token vincolato a quella chiave è inutile senza di essa.

  • Chiedi token vincolati: invia un’intestazione DPoP con le tue richieste di token, e Usher vincola alla tua chiave ciò che emette (token_type è DPoP).
  • Rendili obbligatori: attiva Richiedi DPoP quando crei l’app. Da quel momento Usher non le emette alcun token senza una prova.
  • Usali con Authorization: DPoP <token>, più una prova per quella richiesta.
  • Librerie: la maggior parte delle librerie OAuth con supporto per DPoP fa tutto questo al posto tuo (per esempio, l’opzione DPoP di openid-client).