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:
- Das Gerät sendet eine Token-Anfrage an
/api/oauth/device/codemit seinerclient_idund dem angefordertenscope - Auris gibt einen
device_code(undurchsichtig, lang), einenuser_code(kurz, lesbar, 8 Zeichen), eineverification_uriund ein Abfrage-intervalzurück - Das Gerät zeigt
user_codeundverification_uridem Benutzer an - Der Benutzer besucht die Verifizierungs-URL in einem Browser, gibt den Code ein und authentifiziert sich bei Auris
- Das Gerät fragt unterdessen
POST /api/auth/tokenmitgrant_type=urn:ietf:params:oauth:grant-type:device_codeim angegebenen Interval ab - Sobald der Benutzer genehmigt, gibt die nächste Abfrage ein Access Token und Refresh Token zurück
- 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:
| Einstellung | Standard | Hinweise |
|---|---|---|
| Code-Lebensdauer | 600 Sekunden (10 Minuten) | Maximale Zeit, die der Benutzer hat, um den Code einzugeben und zu genehmigen |
| Abfrage-Interval | 5 Sekunden | Minimales Interval zwischen Token-Abfrageanfragen vom Gerät |
| Benutzercode-Länge | 8 Zeichen | Alphanumerisch, 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
JavaScript SDK
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:
| Feld | Typ | Beschreibung |
|---|---|---|
device_code | string | Undurchsichtiger Code, den das Gerät zum Abfragen des Tokens verwendet. Geheim halten. |
user_code | string | Kurzer alphanumerischer Code (8 Zeichen), der dem Benutzer angezeigt wird. |
verification_uri | string | URL, die der Benutzer besucht, um den Code einzugeben. |
verification_uri_complete | string | URL mit dem Code als Query-Parameter vorausgefüllt. |
expires_in | number | Sekunden bis zum Ablauf des Gerätecodes (Standard: 600). |
interval | number | Minimales Abfrage-Interval in Sekunden (Standard: 5). |
Fehlerbehandlung
Während der Abfragephase gibt der Token-Endpunkt spezifische Fehlercodes zurück, um den aktuellen Zustand anzuzeigen:
| Fehlercode | HTTP-Status | Bedeutung | Client-Aktion |
|---|---|---|---|
authorization_pending | 400 | Benutzer hat die Anfrage noch nicht genehmigt | Weiter im angegebenen Interval abfragen |
slow_down | 428 | Zu häufige Abfragen | Abfrage-Interval um 5 Sekunden erhöhen |
expired_token | 400 | Gerätecode abgelaufen | Flow ab Schritt 1 neu starten |
access_denied | 400 | Benutzer hat die Anfrage explizit abgelehnt | Fehlermeldung 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:
- Fordert den Benutzer zur Eingabe des 8-stelligen Codes auf
- Authentifiziert den Benutzer (Login erforderlich, wenn keine aktive Sitzung)
- Zeigt den anfragenden Anwendungsnamen und angeforderte Scopes an
- Fragt den Benutzer nach Genehmigung oder Ablehnung der Anfrage
- 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
/api/oauth/device/codeFordert 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.
/api/auth/tokenToken-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.
/api/oauth/device/verifyGehostete Verifizierungsseite. Akzeptiert optionalen user_code-Query-Parameter zum Vorausfüllen.
/api/oauth/device/codesRequires: manage:device_codesListet aktive Gerätecodes für den Tenant auf. Admin-Endpunkt für Monitoring und Debugging.
Erforderliche Berechtigungen
| Operation | Berechtigung |
|---|---|
| Device Flow auf einer Anwendung aktivieren | manage:applications |
| Aktive Gerätecodes auflisten | manage:device_codes |
| Gerätecode widerrufen | manage:device_codes |
| Token anfordern/abfragen | Keine Berechtigung erforderlich (öffentlicher Endpunkt) |
Verwandte Anleitungen
- Hosted Login (PKCE) — Browserbasierte interaktive Authentifizierung
- M2M Client Credentials — Server-zu-Server-Authentifizierung ohne Benutzer
- CIBA (Backchannel-Authentifizierung) — Entkoppelte Authentifizierung auf einem separaten Gerät