So funktioniert OAuth — der Authorization-Code-Flow

So funktioniert OAuth — der Authorization-Code-Flow

Die interaktive FlowJam-Zeichenfläche zu dieser Erklärung — jede Bahn, jede Zeile und jeder Pfeil oben gehört zu einem echten QueryChart-Diagramm, das Sie öffnen und bearbeiten können.

So lesen Sie diese Darstellung

• Lesen Sie die drei Spalten von links nach rechts: Autorisierung, Token-Austausch, Geschützte Ressource.
• Jede Zeile ist der Part einer Partei — die Zeile des Nutzers liegt oben, die des Ressourcenservers unten, sodass die Einwilligung des Nutzers und die Prüfung des Servers die Mitte einrahmen.
• Pfeile, die Zeilen überspringen, etwa der Code, der zum Client zurückkehrt, sind echte Netzwerknachrichten zwischen den Parteien; Pfeile innerhalb einer Zeile sind die eigenen Schritte dieser Partei.

Der Autorisierungstanz

„Nutzer klickt auf ‚Mit Anbieter anmelden‘“ beginnt in der Zeile des Nutzers und übergibt an „Client leitet den Nutzer zum Autorisierungsserver“. Die Weiterleitung ist der bestimmende Zug von OAuth: Sie führt den Nutzer AUS der Client-Anwendung heraus zum Anbieter, wo „Nutzer meldet sich an und genehmigt die Scopes“ geschieht. Der Einwilligungsdialog — nicht nur die Anmeldung — ist der Schritt, auf den es ankommt: Der Nutzer wählt genau, was der Client tun darf. „Autorisierungsserver sendet dem Client einen Autorisierungscode“ gibt die Steuerung an die App zurück, aber nur mit einem Code, nicht mit einem Token.

Der Token-Austausch

„Client tauscht Code und Client Secret gegen ein Access Token“ führt aus der Zeile des Clients in die des Autorisierungsservers. In diesem Schritt weist der Client nach, dass er eine legitime Anwendung ist: Er legt den empfangenen Code UND sein registriertes Client Secret vor — ein gestohlener Code allein genügt also nicht. „Autorisierungsserver stellt das Access Token aus“ ist der Moment, in dem aus der Einwilligung eine Berechtigung wird: eine Zeichenkette, die sagt, was der Client tun darf und wie lange.

Das Token einlösen

„Client ruft den Ressourcenserver mit dem Access Token auf“ führt in die Bahnengruppe „Ressourcenserver“, und „Ressourcenserver prüft das Token und gibt die Nutzerdaten zurück“ ist der Ertrag. Der Ressourcenserver sieht weder das Passwort des Nutzers noch den Einwilligungsdialog — er prüft nur das Token. „Nutzer sieht seine Daten in der App“ schließt den Kreis zurück in der Zeile des Nutzers: Aus seiner Sicht hat er sich einmal angemeldet, und die App hat seine Daten bekommen.

Wichtige Zusammenhänge und Erkenntnisse

• Das Passwort des Nutzers erhält nur der Autorisierungsserver — Client und Ressourcenserver sehen es nie.
• Die Einwilligung, also die Scopes, ist die eigentliche Erlaubnis; das Access Token ist diese Erlaubnis in maschinenlesbarer Form.
• Der Autorisierungscode ist kurzlebig und ohne das Client Secret nutzlos — zwei Faktoren schützen den Tausch.
• Access Token laufen ab; Refresh Token stellen im Stillen neue aus, ohne einen weiteren Einwilligungsdialog.
• Die einzige Aufgabe des Ressourcenservers ist es, das Token zu prüfen, und das hält die Parteien entkoppelt.

Wann Sie diese Darstellung nutzen

• Einem Produktteam erklären, warum „Mit Google anmelden“ sicher ist und worum der Einwilligungsdialog bittet.
• Einen OAuth-Flow wählen: den Authorization-Code-Flow hier gegenüber Implicit oder Client Credentials für andere Szenarien.
• Prüfen, wo Zugangsdaten und Token in Ihrer Integration tatsächlich unterwegs sind.

So funktioniert es

1. Benennen Sie die Parteien auf Ihr System um

   Ersetzen Sie die vier Bahnengruppen durch Ihre echten Beteiligten — Ihre Web-App, Ihren Identitätsanbieter, Ihre API —, damit die Grenzen das System abbilden, das Sie dokumentieren.

2. Ergänzen Sie die Scopes, die Sie anfordern

   Vermerken Sie am Einwilligungsschritt die tatsächlichen Scopes und je eine Notiz, warum jeder nötig ist, damit Prüfende die Entscheidung für das geringste Privileg sehen.

3. Zeichnen Sie den Refresh-Pfad

   Ergänzen Sie einen Zweig nach dem Ablauf des Tokens: Der Client legt das Refresh Token vor und erhält ein neues Access Token ohne Einwilligungsdialog, endend in einem eigenen expliziten Zustand.

4. Modellieren Sie die Fehlerfälle

   Ergänzen Sie die Ablehnungszweige — ein abgelehnter Einwilligungsdialog, ein ungültiger Code, ein abgelaufenes oder widerrufenes Token — mit der Fehlerantwort, die sie jeweils erzeugen.

Häufig gestellte Fragen

Was ist OAuth, und warum gibt es das?

OAuth ist ein Standard für Delegation. Er lässt eine Anwendung im Namen eines Nutzers auf dessen Daten bei einem anderen Dienst zugreifen, ohne dass die Anwendung je das Passwort des Nutzers sieht. Der Nutzer authentifiziert sich einmal am Autorisierungsserver und genehmigt bestimmte Berechtigungen (Scopes); die App erhält ein Token, das sie einlösen kann. Genau diese Trennung der Zuständigkeiten stellen die vier Bahnengruppen in der Darstellung dar.

Was ist der Unterschied zwischen einem Autorisierungscode und einem Access Token?

Ein Autorisierungscode ist ein kurzlebiger Zwischenwert, den der Client nach der Einwilligung des Nutzers erhält; für sich allein gewährt er nichts. Der Client tauscht den Code — zusammen mit seinem registrierten Client Secret — gegen ein Access Token, und das ist die eigentliche Berechtigung, mit der er den Ressourcenserver aufruft. Erst der zweistufige Tausch lässt den Client seine Identität am Token-Endpunkt nachweisen.

Warum gibt der Nutzer sein Passwort nicht an die App?

Weil die App nur begrenzten, widerrufbaren Zugriff braucht — ein Profil lesen, nicht ein Konto besitzen. Bekäme die App das Passwort, hätte sie für immer vollen Zugriff, und der Nutzer könnte einer einzelnen App den Zugriff nicht entziehen, ohne sein Passwort überall zu ändern. OAuth tauscht ein Passwort gegen ein begrenztes, ablaufendes Token, das der Nutzer unabhängig widerrufen kann.

Was sind Scopes?

Scopes sind die konkreten Berechtigungen, die der Nutzer erteilt, etwa „E-Mail lesen“ oder „in den Kalender schreiben“. Sie erscheinen im Einwilligungsdialog und werden in das Access Token codiert. Der Ressourcenserver setzt sie durch, sodass ein Token mit Lese-Scope nicht schreiben kann — das geringste Privileg steckt im Protokoll und hängt nicht am Wohlverhalten des Clients.

Diese Darstellung in QueryChart (FlowJam) bearbeiten

Öffnen Sie genau diese OAuth-Zeichenfläche als eigenes Diagramm, benennen Sie die Parteien auf Ihre Dienste um, und vermerken Sie die Scopes, die Sie anfordern.

Diese Darstellung in QueryChart (FlowJam) bearbeiten