spring-boot-jwt: JWT auth service using Spring Boot, Spring Security and MySQL

Ein Spring Boot 3.5 JWT-Dienst mit Entwicklungs-H2-Profil

Die Repository-Metadaten beschreiben einen JWT-Authentifizierungsdienst mit Spring Boot, Spring Security und MySQL. Die Stack-Liste im README zeigt Java 17, Spring Boot 3.5, MySQL, JWT, Refresh-Tokens und SpringDoc OpenAPI. Das Standard-Entwicklungsprofil nutzt eine In-Memory-H2-Datenbank (test_db) mit aktivierter H2-Konsole; die MySQL-URL erscheint nur in einem auskommentierten Beispiel. Das Projekt zielt auf Spring Boot 3.5.x, Java 17+, Spring Security 6, Jakarta-EE-Namespaces, JJWT 0.12.x und SpringDoc. Zum Zeitpunkt des Schreibens hat das Repository 1.686 Sterne und 651 Forks, mit einem offenen Issue. Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht. Abschnitt 1 bleibt auf spring-boot-jwt bezogen und beschreibt nur die im Repository erkennbare Funktion.

Ablauf von Access-Token und Refresh-Token

Die API implementiert ein Muster aus Access-Token und Refresh-Token. Die Anmeldung über POST /users/signin liefert ein JSON-Objekt mit accessToken, refreshToken, tokenType und expiresIn. Das Access-Token ist ein kurzlebiges zustandsloses JWT, das bei jeder Anfrage als Authorization: Bearer <token> gesendet wird. Das Refresh-Token ist eine langfristig gültige opake Zufallszeichenkette, die serverseitig gespeichert wird und nur dazu dient, ein neues Access-Token zu erhalten. Die Endpunkte /users/signin, /users/signup, /users/refresh und /users/logout sind öffentlich; alle anderen erfordern ein gültiges Access-Token. Rollen wie ROLE_ADMIN und ROLE_CLIENT werden über @PreAuthorize an Controller-Methoden durchgesetzt. Das Sequenzdiagramm im README zeigt Anmeldung, geschützte Anfrage und Refresh-Rotation. Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht. Abschnitt 2 bleibt auf spring-boot-jwt bezogen und beschreibt nur die im Repository erkennbare Funktion.

Refresh-Token-Design: opak, gehasht, einmalig

Refresh-Tokens sind 256 Zufallsbits aus SecureRandom, Base64url-kodiert und tragen keine Claims; ihre Bedeutung liegt in der Datenbankzeile, auf die sie verweisen. Gespeichert wird nur der SHA-256-Hash in RefreshToken.tokenHash, sodass ein Datenbankleck keine verwendbaren Tokens preisgibt. Jede Aktualisierung verbraucht das vorgelegte Token und liefert ein Ersatz-Token. Wird ein bereits verbrauchtes Token erneut vorgelegt, widerruft der Dienst alle Refresh-Tokens dieses Benutzers und lehnt die Anfrage ab, was eine neue Anmeldung erzwingt. Das README nennt den Abwägungsgrund: Ein kurzes JWT_EXPIRE_MS verkleinert das Zeitfenster, in dem ein gestohlenes Access-Token funktioniert, kostet aber mehr Refresh-Roundtrips. Access-Tokens selbst können vor Ablauf nicht widerrufen werden. Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht. Abschnitt 3 bleibt auf spring-boot-jwt bezogen und beschreibt nur die im Repository erkennbare Funktion.

Kernklassen im Sicherheitspaket

JwtTokenFilter gilt für alle API-Pfade außer den vier nicht authentifizierten Endpunkten, die über shouldNotFilter übersprungen werden und nicht einfach permitAll sind. Der Grund: Ein Client, der eine abgelaufene Sitzung aktualisiert, sendet oft noch einen veralteten Authorization-Header, und der Filter lehnt ungültige Tokens ab. Der Filter löst und validiert das Token über JwtTokenProvider, das die Signatur prüft und Identitäts- und Autorisierungsclaims extrahiert. RefreshTokenService verwaltet issue, rotate, revoke und deleteAllForUser; rotate ist mit dontRollbackOn = CustomException versehen, damit der durch ein wiederverwendetes Token ausgelöste Fehler den bereits durchgeführten Widerruf nicht zurückrollt. MyUserDetails implementiert UserDetailsService, und WebSecurityConfig definiert eine SecurityFilterChain mit zustandslosen Sessions, deaktiviertem CSRF, requestMatchers und dem JWT-Filter vor UsernamePasswordAuthenticationFilter. Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht. Abschnitt 4 bleibt auf spring-boot-jwt bezogen und beschreibt nur die im Repository erkennbare Funktion.

Demo ausführen und Produktion konfigurieren

Die README-Einrichtung verlangt JDK 17 oder neuer sowie Maven 3.6.3+ oder den mitgelieferten mvnw-Wrapper. Nach dem Klonen und mvn install startet mvn spring-boot:run die Anwendung auf Port 8080. Swagger UI ist unter http://localhost:8080/swagger-ui.html erreichbar, OpenAPI-JSON unter /v3/api-docs. Beim Start werden zwei Demobenutzer idempotent angelegt: admin/admin123456 und client/client123456. Die Konfiguration erfolgt über Umgebungsvariablen: JWT_SECRET (Standard secret-key, nur Entwicklung), JWT_EXPIRE_MS (Standard 300000, fünf Minuten) und JWT_REFRESH_EXPIRE_MS (Standard 604800000, sieben Tage). Für die Produktion rät das README, ein langes zufälliges Secret zu setzen, die H2-Konsole zu deaktivieren und eine echte Datenbank zu verwenden. Docker-Befehle sind docker build -t spring-boot-jwt . und docker run -p 8080:8080 spring-boot-jwt. Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht. Abschnitt 5 bleibt auf spring-boot-jwt bezogen und beschreibt nur die im Repository erkennbare Funktion.

Tests und die Breaking Changes bei der Refresh-Behandlung

Tests laufen mit ./mvnw test. UserControllerTest ist ein integrativer Test mit @SpringBootTest und MockMvc und deckt Anmeldung/Registrierung, rollengeschützte Endpunkte, Refresh-Rotation, Ablehnung wiederverwendeter Tokens, Widerruf der gesamten Token-Familie nach Reuse-Erkennung, Logout sowie das Aktualisieren mit abgelaufenem Access-Token im Authorization-Header ab. Das README dokumentiert auch Breaking Changes für bestehende Forks: Anmeldung und Registrierung liefern jetzt ein JSON-Tokenpaar statt eines nackten Strings, GET /users/refresh wurde entfernt und durch POST /users/refresh ersetzt, das das Refresh-Token entgegennimmt und kein Access-Token benötigt, und POST /users/logout widerruft ein Refresh-Token. Ein Upgrade von Spring Boot 2.x erfordert die Umstellung von javax.* auf jakarta.*, die Übernahme von SecurityFilterChain, den Ersatz von Springfox durch SpringDoc, die Aktualisierung auf JJWT 0.12+ und den Betrieb auf JDK 17+. Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht. Abschnitt 6 bleibt auf spring-boot-jwt bezogen und beschreibt nur die im Repository erkennbare Funktion.

Lizenz und was das README nicht behauptet

Das Projekt steht unter der MIT-Lizenz, Copyright (c) 2017 Mauricio Urraco. Die Lizenz erlaubt die Nutzung, Vervielfältigung, Änderung, Zusammenführung, Veröffentlichung, Verteilung, Unterlizenzierung und den Verkauf von Kopien, sofern der Urheberrechtshinweis enthalten ist. Die Software wird ohne jegliche Gewährleistung bereitgestellt. Der Beitragsabschnitt im README bittet um Issue-Meldungen, Pull Requests und Mundpropaganda, beschreibt aber keine Produktionsbereitstellungen, Leistungsbenchmarks oder Sicherheitsaudits. Die Repository-Metadaten zeigen zum Zeitpunkt des Schreibens ein offenes Issue. Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht. Abschnitt 7 bleibt auf spring-boot-jwt bezogen und beschreibt nur die im Repository erkennbare Funktion.

Redaktionelles Fazit

spring-boot-jwt passt zu Nutzern, deren Aufgabe den im README beschriebenen Rahmen trifft. Es passt nicht als Beleg für unbeschriebene Plattformen, Leistungswerte oder Supportzusagen. Prüfe zuerst Prüfe mit ./mvnw test besonders POST /users/refresh, die Einmalverwendung des Refresh-Tokens und das Verhalten eines abgelaufenen Authorization-Headers. JWT_SECRET und JWT_EXPIRE_MS gehören in eine eigene Testkonfiguration; das Standard-Secret ist laut README nur für Entwicklung gedacht.

Offizielle Quellen

1. Official README
2. Project repository