Wenn Sie danach suchen, wie JWTs bei der Authentifizierung mit E-Mail-Adresse und Passwort eingesetzt werden, stoßen Sie immer wieder auf dieselben Fragen: Ist es sicher, Zugangsdaten in einem Token abzulegen? Brauche ich weiterhin HTTPS? Wer soll dieses Token eigentlich lesen, und was passiert, wenn es abläuft? Die Antworten sind kurz – sie richtig umzusetzen ist der größte Teil der Arbeit.
Dieses Tutorial führt Sie anhand der AuthFlow™ REST API durch den gesamten Lebenszyklus eines JSON Web Tokens in einer App mit E-Mail-Adresse und Passwort – von der ersten Registrierung bis zum Logout. Das Token-Format selbst ist in RFC 7519 definiert; Sie müssen den Standard nicht lesen, um der Anleitung zu folgen.
Was ein JWT ist – und was nicht
Ein JWT ist das Ergebnis einer Authentifizierung, kein Ersatz dafür. Der Benutzer weist einmal mit E-Mail-Adresse und Passwort nach, wer er ist. Anschließend gibt der Server ein signiertes Token zurück, das besagt: „Diese Person hat sich bereits authentifiziert.“ Bei jeder weiteren Anfrage wird das Token statt des Passworts mitgesendet. Dadurch sind JWTs in zustandslosen und verteilten Systemen nützlich: Jeder Dienst mit dem passenden Schlüssel kann das Token prüfen, ohne erneut auf die Datenbank zugreifen zu müssen.
Ein JWT besteht aus drei Teilen: einem Header (Tokentyp und Signaturalgorithmus), einem Payload mit Claims über den Benutzer und einer Signatur. Die Signatur weist nach, dass das Token nicht verändert wurde. Sie verbirgt jedoch keine Inhalte. Der Payload ist lediglich base64-kodiert und kann daher von jeder Person gelesen werden, die das Token erhält. Betrachten Sie ein JWT als manipulationssicher erkennbar, nicht als geheim.
Das Passwort gehört niemals ins Token
Eine häufige Frage von Einsteigern lautet, ob die Zugangsdaten eines Benutzers im JWT gespeichert werden können. In der Regel ist das nicht nötig: Das Token ist selbst ein kurzlebiger Zugangsnachweis, der beim Login ausgestellt wird. Wenn Sie den Benutzer identifizieren müssen, verwenden Sie einen Bezeichner im sub-Claim und ergänzen Sie eine Rolle oder Zugriffsstufe, falls Ihr Backend diese benötigt. Lassen Sie Passwörter, Geheimnisse und alle Angaben weg, die nicht im Browser sichtbar sein sollten.
HTTPS ist ein separates Thema und sollte überall verwendet werden. Es schützt den Datenverkehr zwischen Client und Server, während die JWT-Signatur die Integrität des Tokens schützt. Keines von beiden ersetzt das andere.
Schritt 1: API-Schlüssel auf dem Server behalten
Jeder AuthFlow-Aufruf erfolgt im Namen Ihrer Organisation und verwendet den API-Schlüssel aus dem Owner-Dashboard. Dieser Schlüssel muss auf einer von Ihnen kontrollierten Infrastruktur bleiben, zum Beispiel in einer serverseitigen Umgebungsvariable wie AUTHFLOW_API_KEY. Er darf niemals im JavaScript des Browsers ausgeliefert werden. Am einfachsten und sichersten ist ein kleines Backend (oder unser ExpressJS-Proxy), mit dem Ihr Frontend kommuniziert und das stellvertretend /auth aufruft.
Schritt 2: Registrieren und anmelden
Vor einer Registrierung oder Anmeldung fordert Ihr Backend für die E-Mail-Adresse des Benutzers ein kurzlebiges Anti-Missbrauchs-Token über /auth/fooBar an. Es läuft nach 45 Sekunden ab. Rufen Sie es deshalb unmittelbar vor dem nächsten Aufruf ab und verwenden Sie es niemals erneut. Rufen Sie dann /auth/signUp mit dem Wert foobar, Ihrem api_key, der email, einem password, das die Komplexitätsregeln erfüllt (8 bis 32 Zeichen mit Groß- und Kleinbuchstaben, einer Zahl und einem Sonderzeichen), dem fullname sowie disclaimed mit dem Wert true auf. Bei erfolgreicher Registrierung wird sofort ein Sitzungstoken zurückgegeben; eine bereits vorhandene Kombination aus E-Mail-Adresse und Rolle führt zu 409.
Die Anmeldung funktioniert genauso über /auth/login. Bei Erfolg erhalten Sie das Sitzungstoken: ein mit RS512 signiertes JWT. RS512 verwendet ein Schlüsselpaar. Die Signatur wird mit einem privaten Schlüssel erstellt, den Sie nie zu sehen bekommen, und kann geprüft werden, ohne ein Geheimnis weiterzugeben.
Schritt 3: Token sorgfältig speichern
Sobald Ihr Backend das Token erhalten hat, entscheiden Sie, wo es gespeichert wird. HTTP-only-Cookies sind die empfohlene Option, weil Seitenskripte sie nicht auslesen können. Dadurch werden die möglichen Folgen einer Cross-Site-Scripting-Schwachstelle begrenzt. Bewahren Sie unabhängig von Ihrer Wahl das Sitzungstoken und kein temporäres Token auf, und stellen Sie sicher, dass es niemals in Protokollen landet.
Schritt 4: Jede geschützte Route überprüfen
Prüfen Sie das Token, bevor Ihr Backend eine geschützte Anfrage verarbeitet. Rufen Sie /auth/validate mit sessionToken und der email des Benutzers auf. Ein gültiges Token wird akzeptiert, ein ungültiges oder abgelaufenes führt zu 401. Verwenden Sie /auth/me, wenn Sie das Profil des aktuellen Benutzers benötigen. Diese Prüfung muss bei jeder geschützten Anfrage auf dem Server stattfinden: Ein signiertes Token, das Sie nie verifizieren, bietet keinerlei Schutz.
Der Ablauf ist Teil des Konzepts. Läuft ein Token ab, meldet sich der Benutzer erneut an, statt dass Ihre App versucht, es unbemerkt zu verlängern. Sorgen Sie dafür, dass Ihre App den 401-Status angemessen behandelt und den Benutzer zurück zur Anmeldung leitet.
Schritt 5: Zwei-Faktor-Authentifizierung behandeln
Wenn ein Benutzer 2FA aktiviert hat, gibt /auth/login kein Sitzungstoken zurück. Stattdessen erhalten Sie requires2FA und ein tempToken. Ihre App fordert dann einen zweiten Faktor an und tauscht das tempToken über einen der /auth/2fa-Verifizierungsendpunkte ein (einen TOTP-Code, einen Backup-Code oder ein E-Mail-OTP). Nur dieser Austausch erzeugt das echte Sitzungstoken. Speichern Sie daher unbedingt dieses Token und niemals das tempToken.
Tokens mit jwt.io debuggen
Wenn etwas nicht stimmt, lässt sich mit jwt.io am schnellsten herausfinden, was ein Token tatsächlich enthält. Fügen Sie ein Token in den Debugger ein: Er dekodiert Header und Payload, sodass Sie Algorithmus, sub-Claim und Ablaufzeit prüfen können. Meist reicht das aus, um ein abgelaufenes Token, den falschen Benutzer oder ein versehentlich gespeichertes tempToken zu erkennen.
Aus allem bisher Gesagten folgt eine wichtige Warnung: Ein Token ist ein Zugangsnachweis. Behandeln Sie ein aktives Produktionstoken als vertraulich, verwenden Sie beim Debuggen möglichst Testkonten und fügen Sie echte Tokens nicht in Tools ein, denen Sie nicht vertrauen. Ein Token zu dekodieren ist nicht dasselbe wie es zu verifizieren. Die Verifizierung findet weiterhin auf Ihrem Server über /auth/validate statt.
Schritt 6: Abmelden
Um eine Sitzung zu beenden, rufen Sie /auth/logout mit sessionToken und email auf und entfernen Sie anschließend das Token aus dem Speicherort. Ein Passwortwechsel funktioniert ähnlich über /auth/changePassword. Wenn Sie Authentifizierungsereignisse protokollieren, erhalten Sie einen hilfreichen Verlauf für den Fall, dass etwas schiefgeht.
Checkliste für die JWT-Integration
- Der API-Schlüssel liegt ausschließlich in der serverseitigen Konfiguration, niemals im Browsercode.
- Vor jeder Registrierung und Anmeldung erfolgt ein neuer Aufruf von
/auth/fooBar. - Passwörter und Geheimnisse stehen nicht im Token-Payload; Benutzer werden mit
subund einer Rolle identifiziert. - Das Sitzungstoken wird in einem HTTP-only-Cookie oder einem anderen serverkontrollierten Speicher abgelegt.
- Jede geschützte Route überprüft das Token über
/auth/validate, bevor sie etwas verarbeitet. - Abgelaufene oder ungültige Tokens (401) leiten den Benutzer zurück zur Anmeldung.
- Beim 2FA-Ablauf wird das endgültige Sitzungstoken gespeichert, nicht das
tempToken. - Der gesamte Datenverkehr verwendet HTTPS, und Tokens werden niemals protokolliert.
Damit ist der gesamte Ablauf beschrieben: einmal authentifizieren, ein signiertes Token mitsenden, es auf dem Server prüfen und ablaufen lassen. Im Einstiegsleitfaden finden Sie die vollständige Referenz der Endpunkte; oder vergleichen Sie, wie andere Plattformen damit umgehen. Wenn ein Token verdächtig aussieht, zeigt jwt.io, was darin steht.