Skip to Content

Device Authorization Flow

Der Device Authorization Grant (RFC 8628) ermöglicht es Benutzern, sich auf Geräten anzumelden, die eingeschränkte oder keine Browser-Funktionen haben. Statt Anmeldedaten direkt auf dem Gerät einzugeben, wird dem Benutzer ein Kurzcode und eine URL angezeigt. Der Benutzer besucht die URL auf einem Telefon oder Laptop, gibt den Code ein und genehmigt die Anfrage. Das Gerät fragt währenddessen den Token-Endpunkt ab, bis der Benutzer die Autorisierung abschließt.

Häufige Anwendungsfälle:

  • Smart-TV-Apps, die einen Code auf dem Bildschirm anzeigen, den der Benutzer auf seinem Telefon genehmigt
  • CLI-Tools, die einen Browser öffnen, damit der Benutzer sich authentifizieren kann
  • IoT-Geräte ohne Tastatur oder Bildschirm, die einen Code an die serielle Ausgabe drucken
  • Kiosk- und Kassensysteme

Funktionsweise

Der Device-Flow ist ein Zwei-Kanal-Protokoll. Das Gerät kommuniziert mit dem Token-Endpunkt, während der Benutzer mit Auris in einem Browser auf einem separaten Gerät interagiert:

  1. Das Gerät sendet eine Token-Anfrage an /api/oauth/device/code mit seiner client_id und dem angeforderten scope
  2. Auris gibt einen device_code (undurchsichtig, lang), einen user_code (kurz, lesbar, 8 Zeichen), eine verification_uri und ein Abfrage-interval zurück
  3. Das Gerät zeigt user_code und verification_uri dem Benutzer an
  4. Der Benutzer besucht die Verifizierungs-URL in einem Browser, gibt den Code ein und authentifiziert sich bei Auris
  5. Das Gerät fragt unterdessen POST /api/auth/token mit grant_type=urn:ietf:params:oauth:grant-type:device_code im angegebenen Interval ab
  6. Sobald der Benutzer genehmigt, gibt die nächste Abfrage ein Access Token und Refresh Token zurück
  7. Wenn der Benutzer ablehnt oder der Code abläuft, gibt die Abfrage einen Fehler zurück

Console-Einrichtung

Device Flow aktivieren

Gehe in der Auris Console zu Applications und wähle die Anwendung, die den Device-Flow verwenden soll. Aktiviere unter dem Tab Settings Enable Device Flow.

Einstellungen konfigurieren

Setze die Gerätecode-Lebensdauer und das Abfrage-Interval:

EinstellungStandardHinweise
Code-Lebensdauer600 Sekunden (10 Minuten)Maximale Zeit, die der Benutzer hat, um den Code einzugeben und zu genehmigen
Abfrage-Interval5 SekundenMinimales Interval zwischen Token-Abfrageanfragen vom Gerät
Benutzercode-Länge8 ZeichenAlphanumerisch, Großbuchstaben, leicht zu lesen und zu tippen

Client ID notieren

Device-Flow verwendet einen öffentlichen Client (kein Client-Secret). Kopiere die Client ID vom Tab Credentials.


Implementierung

import { AurisClient } from '@auris/js' const auris = new AurisClient({ domain: 'auth.yourdomain.com', clientId: 'your-device-app-client-id', }) // Schritt 1: Gerätecode anfordern const deviceAuth = await fetch('https://auth.yourdomain.com/api/oauth/device/code', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ client_id: 'your-device-app-client-id', scope: 'openid profile email', }), }).then(r => r.json()) // Schritt 2: Dem Benutzer anzeigen console.log(`Besuche: ${deviceAuth.verification_uri}`) console.log(`Code eingeben: ${deviceAuth.user_code}`) // Schritt 3: Auf Token warten const token = await pollForToken(deviceAuth) async function pollForToken(deviceAuth) { const interval = deviceAuth.interval * 1000 // in ms umwandeln 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.yourdomain.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: 'your-device-app-client-id', }), }) if (response.ok) { return await response.json() } const error = await response.json() if (error.error === 'authorization_pending') { continue // Benutzer hat noch nicht genehmigt } if (error.error === 'slow_down') { await new Promise(resolve => setTimeout(resolve, 5000)) // zurückrudern continue } if (error.error === 'expired_token') { throw new Error('Gerätecode abgelaufen. Bitte Flow neu starten.') } if (error.error === 'access_denied') { throw new Error('Benutzer hat die Autorisierungsanfrage abgelehnt.') } throw new Error(`Unerwarteter Fehler: ${error.error}`) } throw new Error('Gerätecode abgelaufen.') }

Gerätecode-Antwort

Bei der Anforderung eines Gerätecodes gibt Auris folgende Felder zurück:

FeldTypBeschreibung
device_codestringUndurchsichtiger Code, den das Gerät zum Abfragen des Tokens verwendet. Geheim halten.
user_codestringKurzer alphanumerischer Code (8 Zeichen), der dem Benutzer angezeigt wird.
verification_uristringURL, die der Benutzer besucht, um den Code einzugeben.
verification_uri_completestringURL mit dem Code als Query-Parameter vorausgefüllt.
expires_innumberSekunden bis zum Ablauf des Gerätecodes (Standard: 600).
intervalnumberMinimales Abfrage-Interval in Sekunden (Standard: 5).

Fehlerbehandlung

Während der Abfragephase gibt der Token-Endpunkt spezifische Fehlercodes zurück, um den aktuellen Zustand anzuzeigen:

FehlercodeHTTP-StatusBedeutungClient-Aktion
authorization_pending400Benutzer hat die Anfrage noch nicht genehmigtWeiter im angegebenen Interval abfragen
slow_down428Zu häufige AbfragenAbfrage-Interval um 5 Sekunden erhöhen
expired_token400Gerätecode abgelaufenFlow ab Schritt 1 neu starten
access_denied400Benutzer hat die Anfrage explizit abgelehntFehlermeldung anzeigen, nicht erneut versuchen

Respektiere stets den interval-Wert und den slow_down-Fehler. Clients, die zu aggressiv abfragen, erhalten HTTP 428-Antworten und ihr Abfrage-Interval wird zwangsweise erhöht. Wiederholte Verstöße können zum Widerruf des Gerätecodes führen.


Benutzer-Verifizierungsseite

Auris stellt eine gehostete Verifizierungsseite unter /hosted/device bereit, auf der Benutzer ihren Gerätecode eingeben. Die Seite:

  1. Fordert den Benutzer zur Eingabe des 8-stelligen Codes auf
  2. Authentifiziert den Benutzer (Login erforderlich, wenn keine aktive Sitzung)
  3. Zeigt den anfragenden Anwendungsnamen und angeforderte Scopes an
  4. Fragt den Benutzer nach Genehmigung oder Ablehnung der Anfrage
  5. Zeigt eine Bestätigungsnachricht bei Erfolg an

Wenn die verification_uri_complete-URL verwendet wird, ist das Code-Feld vorausgefüllt, was dem Benutzer einen Schritt erspart.


Sicherheitsüberlegungen

  • Kurze Code-Lebensdauer: Gerätecodes laufen standardmäßig nach 600 Sekunden ab. Dies begrenzt das Fenster für Code-Abfang.
  • Menschenlesbare Codes: Die 8-stelligen Benutzercodes verwenden einen eindeutigen Zeichensatz (kein 0/O, 1/I/l-Verwechslung).
  • Rate-limitierte Abfragen: Der Token-Endpunkt erzwingt das Abfrage-Interval. Clients, die zu schnell abfragen, erhalten slow_down-Fehler.
  • Kein Client-Secret: Device-Flow verwendet öffentliche Clients, weil das Gerät kein Secret sicher speichern kann. Scopes sollten entsprechend begrenzt werden.
  • Einmalige Verwendung: Jeder Gerätecode kann nur einmal genehmigt werden. Nach erfolgreicher Token-Ausstellung wird der Code ungültig.

Da Device-Flow öffentliche Clients verwendet, sind die ausgestellten Access-Tokens in der Regel kürzer lebendig als die aus vertraulichen Client-Flows. Erwäge die Verwendung von Refresh-Tokens, um lange Sitzungen ohne erneuten Device-Flow aufrechtzuerhalten.


API-Endpunkte

POST/api/oauth/device/code

Fordert einen neuen Gerätecode an. Erfordert client_id und optionalen scope im Request-Body. Gibt device_code, user_code, verification_uri, expires_in und interval zurück.

POST/api/auth/token

Token-Endpunkt. Für Device-Flow grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code und client_id setzen. Gibt Access Token bei Erfolg oder Fehlercode während der Abfrage zurück.

GET/api/oauth/device/verify

Gehostete Verifizierungsseite. Akzeptiert optionalen user_code-Query-Parameter zum Vorausfüllen.

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

Listet aktive Gerätecodes für den Tenant auf. Admin-Endpunkt für Monitoring und Debugging.


Erforderliche Berechtigungen

OperationBerechtigung
Device Flow auf einer Anwendung aktivierenmanage:applications
Aktive Gerätecodes auflistenmanage:device_codes
Gerätecode widerrufenmanage:device_codes
Token anfordern/abfragenKeine Berechtigung erforderlich (öffentlicher Endpunkt)

Verwandte Anleitungen