Zum Inhalt springen
Usher IdentityUsher Identity
Dokumentation · Fernseher und Befehlszeilentools

Fernseher, Konsolen und Befehlszeilentools

Ein Fernseher kann eine Anmeldeseite nur umständlich anzeigen, und ein Befehlszeilentool sollte nicht nach einem Passwort fragen. Beim Device Flow zeigt das Gerät einen kurzen Code an, und die Person gibt ihn auf ihrem Smartphone oder Computer in die Lobby ihrer Umgebung ein, wo sie bereits angemeldet ist.

Registriere die App

Öffne in Usher Console die Umgebung und dann Anwendungen → Neue Anwendung → TV oder Befehlszeile. Die App bekommt eine Client-ID und kein Secret: Ein Gerät kann keines geheim halten.

Der 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": "…" }
  • Frag geduldig nach. Warte zwischen zwei Abfragen interval Sekunden. Wer schneller abfragt, bekommt slow_down zur Antwort.
  • Hör auf, wenn es so weit ist. access_denied heißt, dass die Person abgelehnt hat; expired_token heißt, dass zehn Minuten vergangen sind. Fordere einen neuen Code an.
  • Zeig auch die Adresse an. Nicht jeder kann einen QR-Code scannen: Zeig verification_uri und den Code an, gegliedert wie 6L95-PBQQ.

Unter /device zeigt die Lobby der Person, welche App fragt und wofür. Sie rät ihr, nur fortzufahren, wenn sie den Vorgang selbst gestartet hat und ihr Gerät denselben Code zeigt.

Tokens an das Gerät binden (DPoP)

Ein Token, das von einem Gerät kopiert wurde, bleibt ein Token. Mit DPoP (RFC 9449) behält das Gerät einen privaten Schlüssel und schickt bei jeder Anfrage einen frisch signierten Nachweis mit. Ein an diesen Schlüssel gebundenes Token ist ohne ihn nutzlos.

  • Gebundene Tokens anfordern: Sende bei deinen Token-Anfragen einen DPoP-Header mit, und Usher bindet, was es ausstellt, an deinen Schlüssel (token_type ist dann DPoP).
  • Gebundene Tokens verlangen: Aktiviere beim Anlegen der App DPoP verlangen. Usher stellt ihr dann kein Token ohne Nachweis mehr aus.
  • Verwenden mit Authorization: DPoP <token>, plus einem Nachweis für genau diese Anfrage.
  • Bibliotheken: Die meisten OAuth-Bibliotheken mit DPoP-Unterstützung erledigen all das für dich (zum Beispiel die Option DPoP von openid-client).