OAuth2 Device Flow für CLI-Tools und Headless-Clients

1. Warum klassisches OAuth2 für Headless-Clients nicht funktioniert

Der Standard-Authorization-Code-Flow erfordert, dass der Client eine Redirect-URI registriert, zu der der Autorisierungsserver den Nutzer nach erfolgreicher Anmeldung zurückleitet, was voraussetzt, dass der Client selbst einen eingebetteten oder systemeigenen Browser steuern und den Redirect empfangen kann. Ein CLI-Tool, das auf einem entfernten Server ohne jede grafische Oberfläche läuft, ein Smart-TV mit stark eingeschränkter Texteingabe über eine einfache Fernbedienung, oder ein IoT-Gerät völlig ohne jeden Bildschirm können diese grundlegende Voraussetzung strukturell und grundsätzlich niemals erfüllen.

Frühere, deutlich unsichere Workarounds wie das direkte Abfragen von Nutzername und Passwort im CLI-Tool selbst (der sogenannte Resource Owner Password Credentials Grant) sind aus mehreren gewichtigen Gründen problematisch: Das Tool muss die tatsächlichen Zugangsdaten des Nutzers verarbeiten, Zwei-Faktor-Authentifizierung lässt sich darüber kaum abbilden, und der Nutzer muss dem Tool blind vertrauen, dass es die Zugangsdaten nicht missbräuchlich speichert oder weiterleitet.

2. Der Device-Flow-Ablauf Schritt für Schritt

Der Client (etwa ein CLI-Tool) fordert zunächst einen Device Code und einen kurzen, für Menschen leicht abtippbaren User Code vom Autorisierungsserver an, zusammen mit einer Verifizierungs-URL. Das Tool zeigt dem Nutzer diese URL und den User Code direkt im Terminal an (etwa "Öffne https://example.com/device und gib den Code ABCD-1234 ein"), während es selbst im Hintergrund periodisch beim Autorisierungsserver nachfragt, ob die Autorisierung bereits abgeschlossen wurde.

Der Nutzer öffnet die angezeigte URL bequem auf einem beliebigen anderen Gerät mit vollwertigem Browser (typischerweise dem eigenen Smartphone oder Laptop), meldet sich dort ganz normal an, gibt den kurzen, angezeigten User Code sorgfältig ein und bestätigt anschließend die eigentliche Autorisierung. Sobald diese Bestätigung tatsächlich erfolgt ist, erhält das ursprünglich geduldig wartende CLI-Tool bei seiner nächsten regulären Polling-Anfrage die tatsächlichen Access- und Refresh-Tokens zurück und kann seine eigentliche Arbeit normal fortsetzen.

<?php
declare(strict_types=1);

final class DeviceAuthorizationController
{
    public function requestDeviceCode(): array
    {
        $deviceCode = bin2hex(random_bytes(32));
        $userCode = strtoupper(bin2hex(random_bytes(4)));

        $this->deviceCodeRepository->store($deviceCode, $userCode, [
            'status' => 'pending',
            'expiresAt' => new \DateTimeImmutable('+10 minutes'),
        ]);

        return [
            'device_code' => $deviceCode,
            'user_code' => $userCode,
            'verification_uri' => 'https://example.com/device',
            'expires_in' => 600,
            'interval' => 5,
        ];
    }

    public function pollToken(string $deviceCode): array
    {
        $entry = $this->deviceCodeRepository->find($deviceCode);
        if ($entry === null || $entry->isExpired()) {
            return ['error' => 'expired_token'];
        }
        if ($entry->status === 'pending') {
            return ['error' => 'authorization_pending'];
        }

        return $this->tokenService->issueTokens($entry->userId);
    }
}

3. User-Code-Design: kurz, eindeutig, tippfehlerresistent

Der User Code muss von Menschen fehlerfrei von einem Bildschirm abgelesen und auf einer anderen Tastatur eingetippt werden können, weshalb Designentscheidungen wie das Weglassen leicht verwechselbarer Zeichen (0 und O, 1 und I und l) und eine Gruppierung in kurze Blöcke mit Trennzeichen (etwa ABCD-1234 statt ABCD1234) die Fehlerrate bei der manuellen Eingabe deutlich reduzieren. RFC 8628 empfiehlt explizit und ausdrücklich ein eingeschränktes Zeichen-Set genau aus diesem Grund.

Die konkrete Länge des User Codes ist letztlich ein Kompromiss zwischen Sicherheit (ein zu kurzer Code lässt sich potenziell erraten oder systematisch durch Ausprobieren finden) und praktischer Benutzerfreundlichkeit (ein zu langer Code ist mühsam und deutlich fehleranfälliger einzutippen). Ein achtstelliger Code aus einem bewusst eingeschränkten, eindeutigen Zeichensatz ist ein verbreiteter, praxiserprobter Kompromiss zwischen diesen beiden gegenläufigen Anforderungen.

4. Polling-Intervalle korrekt einhalten

Der Autorisierungsserver gibt in seiner initialen Antwort ein interval-Feld zurück, das dem Client mitteilt, wie oft er höchstens beim Token-Endpoint nachfragen darf, ohne als zu aggressiv abgelehnt zu werden. Ein Client, der dieses Intervall ignoriert und zu häufig anfragt, riskiert eine slow_down-Fehlerantwort, die ihn zwingt, das Intervall künftig zu erhöhen, statt weiterhin im ursprünglichen, zu kurzen Takt anzufragen.

Diese bewusste Rate-Begrenzung schützt den Autorisierungsserver zuverlässig vor exzessiver Last durch viele gleichzeitig wartende Device-Flow-Clients, ist aber gleichzeitig auch aus reiner Nutzersicht durchaus sinnvoll: Ein Nutzer, der bewusst etwas Zeit braucht, um die Verifizierungs-URL auf einem anderen Gerät überhaupt erst zu öffnen, erzeugt in dieser Wartezeit ohnehin keine sinnvolle, echte Notwendigkeit für ein sekündliches, hochfrequentes Polling.

5. Ablaufzeit und Timeout-Verhalten des Device Codes

Der Device Code selbst hat eine begrenzte Gültigkeitsdauer (üblicherweise 10 bis 15 Minuten, im expires_in-Feld der initialen Antwort kommuniziert), nach deren Ablauf der Autorisierungsvorgang endgültig fehlschlägt, auch wenn der Nutzer die Verifizierungs-URL noch nicht besucht hat. Der Client sollte diese Ablaufzeit dem Nutzer im Terminal sichtbar anzeigen und nach Ablauf eine klare Fehlermeldung ausgeben, statt endlos weiter zu pollen.

Diese bewusst begrenzte Gültigkeit ist eine wichtige, gezielte Sicherheitsmaßnahme: Ein unbegrenzt gültiger Device Code würde das potenzielle Zeitfenster für einen Angreifer deutlich vergrößern, der versucht, einen abgefangenen oder erratenen User Code für eine eigene, betrügerische Autorisierung zu missbrauchen, während der eigentliche, legitime Nutzer den ursprünglichen Vorgang längst vergessen hat.

6. Typische Einsatzszenarien jenseits von CLI-Tools

Neben klassischen Kommandozeilen-Tools ist der Device Flow der Standardansatz für Smart-TV-Apps (Netflix, YouTube und ähnliche Dienste nutzen ihn für die initiale Geräteverknüpfung), für IoT-Geräte mit sehr eingeschränkter oder fehlender Eingabemöglichkeit, und für Entwicklungswerkzeuge, die sich gegen eine Cloud-API authentifizieren müssen, ohne selbst einen vollwertigen Browser einzubetten (etwa die GitHub-CLI gh auth login).

Das gemeinsame, verbindende Merkmal all dieser unterschiedlichen Szenarien ist stets ein Gerät mit deutlich eingeschränkten Input- oder Browser-Fähigkeiten, kombiniert mit der plausiblen Annahme, dass der jeweilige Nutzer gleichzeitig Zugriff auf ein zweites, voll ausgestattetes Gerät hat, was für die ganz überwiegende Mehrheit realer Nutzungsszenarien eine vernünftige, durchaus praxisnahe Annahme darstellt.

7. Sicherheitsaspekte, die bei der Implementierung beachtet werden müssen

Die Verifizierungsseite, auf der der Nutzer den User Code eingibt, sollte den Nutzer klar über die Art der Autorisierung informieren (welches Gerät, welche Anwendung, welche angeforderten Berechtigungen), damit ein Nutzer eine bösartige oder versehentliche Anfrage erkennen und ablehnen kann, statt jede Autorisierungsanfrage blind zu bestätigen. Diese Transparenz ist besonders wichtig, weil der Device Flow strukturell durchaus anfällig für Phishing-Angriffe ist, wenn ein Angreifer einen ahnungslosen Nutzer geschickt dazu verleitet, einen von ihm selbst kontrollierten Device Code auf der eigentlich legitimen Verifizierungsseite versehentlich zu bestätigen.

Der Autorisierungsserver sollte zusätzlich konsequent die Anzahl fehlgeschlagener User-Code-Eingabeversuche begrenzen, um gezielte Brute-Force-Angriffe auf den vergleichsweise kurzen, für Menschen gut lesbaren Code wirksam zu verhindern, ganz analog zum üblichen Rate-Limiting bei klassischen Login-Formularen im Web.

8. Token-Lifecycle nach erfolgreichem Device Flow verwalten

Nach Abschluss des Device Flow erhält der Client dieselben Access- und Refresh-Tokens wie bei jedem anderen OAuth2-Grant-Typ, weshalb sich die anschließende Token-Verwaltung (Ablauf, Refresh, Widerruf) nicht vom Standard-Flow unterscheidet. Ein CLI-Tool sollte den erhaltenen Refresh-Token sicher im Betriebssystem-Schlüsselbund statt in einer Klartext-Konfigurationsdatei speichern, um versehentliches Auslesen durch andere lokale Prozesse oder ein versehentliches Einchecken in ein Repository zu verhindern.

Für Geräte ohne Betriebssystem-Schlüsselbund (etwa manche IoT-Geräte) sollte zumindest eine restriktive Dateisystem-Berechtigung für die gespeicherten Tokens gesetzt werden, kombiniert mit einer kurzen Access-Token-Lebensdauer, damit ein kompromittiertes, aber lokal gespeichertes Token nur ein begrenztes Zeitfenster für Missbrauch bietet.

9. OAuth2-Flows im Überblick

Die folgende Tabelle vergleicht den Device Flow mit anderen OAuth2-Grant-Typen.

10. Zusammenfassung

11. FAQ: Device Flow: Das Wichtigste auf einen Blick