Direct naar de inhoud
Usher IdentityUsher Identity
Documentatie · Tv’s en opdrachtregeltools

Tv’s, consoles en opdrachtregeltools

Een tv kan niet makkelijk een inlogpagina tonen, en een opdrachtregeltool hoort niet om een wachtwoord te vragen. Met de apparaatflow toont het apparaat een korte code, die iemand intypt in de Lobby van de omgeving, op een telefoon of computer waarop diegene al is ingelogd.

Registreer de app

Open in Usher Console de omgeving en kies Applicaties → Nieuwe applicatie → Tv of opdrachtregel. De app krijgt een client-ID en geen geheim: een apparaat kan een geheim niet geheimhouden.

De flow

Terminal
# 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": "…" }
  • Vraag beleefd. Wacht interval seconden tussen twee pogingen. Wie sneller pollt, krijgt slow_down als antwoord.
  • Stop als dat gevraagd wordt. access_denied betekent dat iemand heeft geweigerd; expired_token betekent dat er tien minuten voorbij zijn. Vraag een nieuwe code aan.
  • Toon ook het adres. Niet iedereen kan een QR-code scannen: toon verification_uri en de code, opgedeeld zoals 6L95-PBQQ.

Op /device laat de Lobby zien welke app erom vraagt en waarvoor. Iemand mag alleen verdergaan als die het zelf heeft gestart en het apparaat dezelfde code toont.

Bind tokens aan het apparaat (DPoP)

Een token dat van een apparaat is gekopieerd, is nog steeds een token. Met DPoP (RFC 9449) bewaart het apparaat een privésleutel en stuurt het bij elk verzoek een nieuw ondertekend bewijs mee. Een token dat aan die sleutel is gebonden, is zonder die sleutel waardeloos.

  • Vraag om gebonden tokens: stuur een DPoP-header mee met je tokenverzoeken, en Usher bindt wat het uitgeeft aan je sleutel (token_type is DPoP).
  • Maak ze verplicht: zet Vereis DPoP aan als je de app aanmaakt. Usher geeft die app dan geen enkel token zonder bewijs.
  • Gebruik ze met Authorization: DPoP <token>, plus een bewijs voor dat verzoek.
  • Bibliotheken: de meeste OAuth-bibliotheken met DPoP-ondersteuning regelen dit allemaal voor je (bijvoorbeeld de DPoP-optie van openid-client).