Sequenzdiagramm-Beispiel: der OAuth-2.0-Authorization-Code-Flow mit PKCE

Ein Architekturdiagramm zeigt, wer mit wem spricht. Es kann nicht zeigen, in welcher Reihenfolge oder wer auf wen wartet, und bei vielen Problemen ist genau diese Reihenfolge die ganze Geschichte. Login-Flows sind der klassische Fall: Dieselben fünf Nachrichten in anderer Reihenfolge sind eine Sicherheitslücke.

Dieser Guide erklärt die Notation von Sequenzdiagrammen an einem Flow, dem die meisten Entwickler früher oder später begegnen: eine Single-Page-App, die Nutzer über den OAuth-2.0-Authorization-Code-Flow mit PKCE anmeldet und dann eine API aufruft.

Was ein Sequenzdiagramm zeigt

Die Zeit läuft nach unten. Jeder Beteiligte bekommt eine Lebenslinie, eine Box mit einer gestrichelten Linie darunter, und jede Nachricht ist ein waagerechter Pfeil vom Sender zum Empfänger. Von oben nach unten gelesen ergibt sich die Reihenfolge der Ereignisse; quer gelesen siehst du, wer an jedem Schritt beteiligt ist.

Die Notation laut UML-2.5.1-Spezifikation:

Der Flow: Authorization Code mit PKCE

Eine Single-Page-App ist ein öffentlicher Client: Alles, was sie an den Browser ausliefert, ist lesbar, also kann sie kein Client Secret geheim halten. PKCE, definiert in RFC 7636, schützt den Authorization Code trotzdem: Die App beweist, dass derjenige, der den Code einlöst, dieselbe Instanz ist, die den Flow gestartet hat. Die Best Current Practice zur OAuth-2.0-Sicherheit, RFC 9700, schreibt PKCE für öffentliche Clients vor, empfiehlt es für alle anderen und sagt, dass Clients den Implicit Grant nicht verwenden sollten.

Die Schritte:

1. Der Nutzer wählt Anmelden.
2. Die App erzeugt einen Code Verifier und eine Challenge. Der code_verifier ist ein zufälliger String mit 43 bis 128 Zeichen. Die code_challenge ist BASE64URL(SHA256(code_verifier)), die Methode S256. Außerdem speichert die App einen zufälligen state.
3. Die App schickt den Browser mit der Challenge zum Authorization-Endpunkt:

GET /authorize?response_type=code
    &client_id=orders-spa
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
    &scope=orders.read
    &state=af0ifjsldkj
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256 HTTP/1.1
Host: auth.example.com

4. Der Autorisierungsserver meldet den Nutzer an und fragt nach der Einwilligung.
5. Er leitet zurück an die redirect_uri, mit einem kurzlebigen code und demselben state.
6. Die App prüft state gegen den gespeicherten Wert.
7. Die App löst den Code am Token-Endpunkt ein und schickt dabei den aufbewahrten Verifier mit:

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&client_id=orders-spa&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

8. Der Autorisierungsserver hasht den Verifier und vergleicht das Ergebnis mit der Challenge aus Schritt 3. Stimmen sie überein, gibt er ein Access Token zurück und, falls er welche ausstellt, ein Refresh Token.
9. Die App ruft die API auf, mit Authorization: Bearer <access token>.
10. Die API validiert das Token, etwa Signatur, Aussteller, Audience, Ablauf und Scope, und antwortet.

Verifier und Challenge oben sind die Beispielwerte aus RFC 7636; du kannst die S256-Berechnung also selbst nachprüfen.

Das Diagramm

So liest du es:

• Vier Beteiligte in einer Reihe: der Nutzer als Akteur, dann Lebenslinien für die Browser-App, den Autorisierungsserver und die API. Jede Nachricht ist ein waagerechter Pfeil auf eigener Höhe, der Reihe nach nummeriert.
• Die Nachrichten 2 bis 7 sind der Authorization Code Flow. Die Notizen zeigen die zwei Prüfungen, die ihn sicher machen: Die App vergleicht state nach der Weiterleitung, und der Autorisierungsserver vergleicht den gehashten Verifier mit der Challenge.
• Die Nachrichten 8 und 9 sind der API-Aufruf. Antworten sind gestrichelt und haben offene Pfeilspitzen.
• Das opt-Fragment deckt den Fall ab, dass das Access Token abgelaufen ist: eine 401, ein Refresh und ein neuer Versuch.

Zeig den Fehlerpfad, nicht nur den Happy Path

Die meisten Sequenzdiagramme enden bei „200 OK“. Die interessanten Bugs stecken in den Verzweigungen, also zeichne zumindest die, die jeden Tag vorkommt. Nimm alt, wenn das Diagramm mehrere sich gegenseitig ausschließende Zweige mit je einer Bedingung zeigt, und opt für einen Teil, der nur läuft, wenn seine Bedingung wahr ist. Das Refresh hier ist ein opt: Es passiert nur, wenn das Access Token abgelaufen ist.

Der Refresh-Zweig hat eigene Regeln. In Browser-Apps sind Refresh Tokens meist Bearer Tokens. Deshalb verlangen RFC 9700 und RFC 10017, die im August 2026 veröffentlichte Best Current Practice für browserbasierte Apps, dass der Autorisierungsserver sie bei jeder Nutzung rotiert oder an den Client bindet und ihre Lebensdauer begrenzt. Deshalb liefert Nachricht 13 ein neues Refresh Token.

RFC 10017 ordnet außerdem die Architekturen für Browser-Apps nach Sicherheit. Ein Backend-for-Frontend, das die Tokens auf dem Server hält, ist am stärksten; eine Browser-App, die selbst als OAuth-Client agiert wie in diesem Diagramm, ist am einfachsten und am stärksten bösartigem JavaScript ausgesetzt. Wenn du das Browser-Muster wählst, ist das Diagramm ein guter Ort, um zu begründen, warum.

Typische Fehler in Sequenzdiagrammen

• Zu viele Lebenslinien. Ab sechs oder sieben kollidieren Beschriftungen und Leser verlieren den Faden. Teile den Flow auf oder fasse interne Services hinter einer Lebenslinie zusammen.
• Unbeschriftete Antworten. „Antwort“ sagt nichts. Schreib den Status oder den Inhalt: „302 mit code“, „401 invalid_token“.
• Gemischte Detailstufen. HTTP-Parameter an einem Pfeil und „Nutzer ist zufrieden“ am nächsten verwirren beide Zielgruppen. Wähl eine Ebene und bleib dabei.
• Nur der Happy Path. Timeouts, Wiederholungen und abgelaufene Credentials sind genau die Stellen, an denen sich Diagramme auszahlen.
• Jeder Parameter. Zeig die, die Leser prüfen müssen, etwa state, code_challenge und code_verifier, und überlass den Rest der API-Referenz.

Wann es passt und wann nicht

Nutze ein Sequenzdiagramm für Protokolle, Handshakes, Wiederholungen, Timeouts, Race Conditions und Incident-Zeitleisten, also alles, bei dem Reihenfolge und Warten zählen. Nimm etwas anderes für statische Struktur (ein Architektur- oder C4-Diagramm), für Event-Fan-out an viele Consumer (ereignisgesteuerte Architektur als Diagramm) und für Security-Reviews, die zeigen, wo Daten Vertrauensgrenzen überschreiten (Datenflussdiagramme für die Bedrohungsmodellierung).

In Archboard nachbauen

1. Melde dich mit Google oder GitHub an und leg ein Diagramm an.
2. Füge aus dem Sequenz-Pack einen Akteur für den Nutzer und drei Lebenslinie-Nodes für die Browser-App, den Autorisierungsserver und die API hinzu, in einer Reihe und gleich hoch.
3. Zeichne jede Nachricht als gerade Kante zwischen zwei Lebenslinien, von oben nach unten, mit nummerierter Beschriftung. Stell Antworten gestrichelt dar.
4. Füge um die Nachrichten 10 bis 14 ein Kombiniertes Fragment hinzu, setz den Operator auf opt und die Beschriftung auf „[access token expired]“.
5. Füge Notiz-Nodes aus dem UML-Pack für die Prüfungen hinzu: state, den gehashten Verifier und die Token-Validierung.

Das Beispiel nutzt 5 Diagramm-Nodes und bleibt damit im Free-Plan. Archboards eigener MCP-Server meldet KI-Apps genau mit diesem Flow an, dem Authorization Code Grant mit PKCE (S256); mehr dazu unter So erstellst du Architekturdiagramme mit KI-Agenten.

FAQ

Ist PKCE nur etwas für mobile Apps? Nein. Es wurde für native Apps entworfen, aber RFC 9700 schreibt es für alle öffentlichen Clients vor, auch für Single-Page-Apps, und empfiehlt es auch für vertrauliche Clients.

Sollte eine Single-Page-App den Implicit Flow verwenden? Nein. RFC 9700 sagt, dass Clients den Implicit Grant nicht verwenden sollten. Nutze den Authorization Code Flow mit PKCE.

Ist OAuth 2.1 ein fertiger Standard? Zum Zeitpunkt dieses Artikels (Oktober 2026) nicht. Es ist weiterhin ein IETF-Internet-Draft, der OAuth 2.0 und seine Sicherheitspraktiken einschließlich PKCE zusammenführt.

Was ist der Unterschied zwischen alt und opt? alt enthält zwei oder mehr sich gegenseitig ausschließende Zweige mit je einer Bedingung. opt enthält einen Teil, der nur läuft, wenn seine Bedingung wahr ist.

Wie viele Nachrichten passen in ein Sequenzdiagramm? So viele, wie in der Größe lesbar bleiben, in der Leute es ansehen, meist 15 bis 20. Teile längere Flows auf mehrere Diagramme auf, eines pro Phase.

Kostenlos starten — ein Seat, keine Kreditkarte.