Integration von OAuth 2.0 in Spring Boot mit Keycloak

Dieser Leitfaden beschreibt die Integration von OAuth 2.0 in eine Spring Boot Anwendung mit Keycloak. Nach einer kurzen Einführung in die Spring Boot Plattform liegt der Schwerpunkt auf der genauen Konfiguration von Keycloak als vertrauenswürdigen OAuth 2.0 Server und der Absicherung bestimmter Endpunkte in der Anwendung mit Anmeldedaten.

Der Beitrag ist dabei so strukturiert, dass Entwickler Schritt für Schritt eine sichere Authentifizierung in einer Spring Boot-Anwendung implementieren können.

KI generiertes Symbolbild: compelling, light-hearted tone, humorous, illustration, logo-style, spring boot (footwear), security key, keylock, keycloak oauth2, symbolizing secure access

Inhaltsverzeichnis

Spring Boot: Setup und Grundkonfiguration

Konfiguration

Die Vorbereitung der Spring Boot Anwendung für die Integration von OAuth 2.0 beginnt mit der Einrichtung des Projektes.

Für diesen Leitfaden wurde folgende Konfiguration gewählt:

  • Spring Boot v3.2.0
  • Kotlin als Programmiersprache für Spring
  • Gradle (Groovy) für das Build-Tool

Als Vorbereitung für die spätere Integration von OAuth 2.0 werden zudem noch folgende Abhängigkeiten benötigt:

Diese Konfiguration bildet die Grundlage für die Entwicklung der Webanwendung mit integriertem OAuth 2.0 als Sicherheitsmechanismus. Die spezifische Konfiguration kann als neues leeres Projekt hier über den Spring Initializr direkt geladen werden.

Anwendung für OAuth 2.0 vorbereiten

Bevor die Anwendung erstmalig gestartet wird, sollten noch die folgenden Anpassungen vorgenommen werden. Durch die Einbindung der Spring Security Abhängigkeit, ist bereits die gesamte Anwendung mit allen Endpunkten standardmäßig mit einer simplen User/Passwort-Authentifizierung abgesichert. Da OAuth 2.0 später nur für bestimmte Endpunkte verwendet werden soll, ist eine entsprechende Konfiguration von Spring Security erforderlich, bei der diese grundlegende Authentifizierung durch eine Annotation in der Datei DemoApplication.kt vorerst deaktiviert wird. Zu Testzwecken wird ein Endpunkt in einem neuen Controller DemoController.kt definiert. Der Endpunkt und die Deaktivierung der Authentifizierung werden zu einem späteren Zeitpunkt wieder entfernt, wenn OAuth 2.0 konfiguriert wird.

Mit dem Befehl ./gradlew bootRun wird die Anwendung über das Terminal gestartet und ist anschließend unter der Adresse http://localhost:8080 erreichbar.

Ausgabe von "Hello World!" auf http://localhost:8080

Als Vorbereitung für die spätere Integration von OAuth 2.0 werden zwei weitere Endpunkte implementiert — ein öffentlicher Endpunkt /public und ein privater Endpunkt /private, welcher später nur für authentifizierte Benutzer aufrufbar sein soll. Unser „Hello World!“ Endpunkt wird wieder entfernt:

Im Folgenden wollen wir mit OAuth 2.0 den Endpunkt /private absichern, der in diesem Zustand noch ohne Authentifizierung erreichbar ist.

Installation & Konfiguration von Keycloak

Keycloak ist eine Open-Source-Identitäts- und Zugriffsmanagementlösung. Es fungiert als OAuth 2.0 Server und ermöglicht die Authentifizierung von Benutzern, die Verwaltung von Anwendungs-Berechtigungen und die Bereitstellung von Single Sign-On für Anwendungen.

Einrichtung mit Docker

Die Verwendung von Docker ermöglicht den Betrieb einer konsistente und isolierte Umgebung für Keycloak. Zusätzlich wird die Einrichtung erleichtert und sichergestellt, dass alle erforderlichen Abhängigkeiten vorhanden sind und reibungslos funktionieren. Da bereits eine ausführliche Anleitung auf der offiziellen Keycloak-Seite zu finden ist, wird im Folgenden nur noch auf die relevanten Punkte eingegangen. Bevor Keycloak in einem Docker-Container gestartet werden kann, sollten sichergestellt werden, dass Docker auf dem System installiert und einsatzbereit ist. Dies kann mit dem Befehl docker −−version getestet werden, wobei Die Ausgabe die Installierte Docker-Version anzeigen muss. Eine Installationsanleitung für Docker selbst kann der offziellen Seite entnommen werden. Zur eigentlichen Installation und Starten von Keycloak verwenden wir folgenden Befehl:
docker run -p 8081:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak start-dev

Der Befehl setzt sich dabei folgendermaßen zusammen:

  • docker run Anweisung an Docker den Container mit den Parametern zu starten
  • -p 8081:8080 Portmapping von 8081 (Container außen) zu 8080 (Container innen)
  • -e KEYCLOAK_ADMIN=admin Benutzername für das Keycloak Webinterface
  • -e KEYCLOAK_ADMIN_PASSWORD=admin Passwort für das Keycloak Webinterface
  • quay.io/keycloak/keycloak URL auf das Docker-Image für Keycloak
  • start-dev Startet Keycloak innerhalb des Docker-Containers

Sofern lokal noch kein Keycloak Docker-Image existiert, wird dieses automatisch heruntergeladen. Wenn der Befehl ausgeführt wird, startet ein neuer Keycloak-Container, welcher über http://localhost:8081 erreichbar ist. In der Administrationskonsole unter http://localhost:8081/admin kann sich mit den definierten Benutzerdaten angemeldet werden, um Keycloak für den OAuth 2.0 Server zu konfigurieren.

OAuth 2.0 Server Konfiguration

In der Administrationskonsole wird zuerst neuer Realm für die Anwendung erstellt. Bei einem Realm in Keycloak handelt es sich um eine isolierte Sicherheitsdomäne, die Benutzer, Ressourcen und Einstellungen in einem OAuth 2.0 Server organisiert. Auf diese Weise ist eine flexible Verwaltung verschiedener Anwendungen in ein und derselben Keycloak-Instanz möglich. Standardmäßig ist der build-in Realm master ausgewählt. Der Reiter wird angeklickt und über die Schaltfläche Create realm wird ein neuer Realm erstellt. Beim Anlegen wird ein Name vergeben demo-realm vergeben , und sichergestellt, dass dieser aktiv ist.

Nun müssen wir für die Anwendung ein Mandant anlegen. Ein Mandant in Keycloak repräsentiert eine Anwendung, die OAuth 2.0 oder OpenID Connect zur Authentifizierung und Autorisierung verwendet. Jeder Mandant hat eine eindeutige Identität und Konfiguration und kann Ressourcen in einem bestimmten Realm schützen. Beispiele für Mandanten sind Webanwendungen, mobile Anwendungen oder Dienste, die Zugriff auf geschützte Ressourcen benötigen. Zur Erstellung eines neuen Mandanten kann im Menüpunkt Clients der Button Create client angeklickt werden, worauf ein Formular erscheint, das in drei Schritte gegliedert ist:

  1. Schritt: Für den Client wird der Typ OpenID Connect ausgewählt und die Client-ID demo-client vergeben .
  2. Schritt: In diesem Schritt muss sichergestellt werden, dass unter „Authentication flow“ die Option Standard flow aktiviert ist. Die Aktivierung der Option „Standard flow“ in Keycloak ist entscheidend, um die Sicherheit zu erhöhen, indem der Authentifizierungsprozess in zwei Schritte aufgeteilt wird: Der Benutzer authentifiziert sich am Autorisierungsserver und tauscht sicher einen temporären Autorisierungscode gegen Zugriffstoken aus. Dies minimiert das Risiko, sensible Informationen am Frontend preiszugeben, insbesondere bei serverseitigen Anwendungen wie Spring Boot.
  3. Schritt: Hier wird im Feld Valid redirect URIs die URL http://localhost:8080/* eingetragen und alle Eingaben mit einem Klick auf Save bestätigt. Dieser Eintrag ist erforderlich, damit Keycloak nach der Benutzerauthentifizierung die korrekte Rücksendeadresse für den Authorisierungscode erhält. Der Stern ermöglicht die Annahme gültiger Redirect-URIs für alle Pfade unter http://localhost:8080/. Dies bietet Flexibilität für verschiedene Endpunkte und unterstützt die sichere Rückgabe von Authentifizierungsantworten.
 

Damit wäre Keycloak bereits als OAuth 2.0 Server für die Anwendung konfiguriert.

Rollenverwaltung

Die Benutzer müssen mit einem Rollenattribut versehen werden, welches über den Token an die Anwendung weitergegeben werden muss. Zu diesem Zweck muss der Mandant noch weiter konfiguriert werden.

Um eine neue Rolle anzulegen, wird über den Menüpunkt Clients in den angelegten Mandanten demo-client navigiert. Hier wird über den Reiter Roles und den Button Create role eine neue Rolle angelegt. Für die neue Rolle wird der Rollenname demo-role gewählt und anschließend mit dem Button Save bestätigt. Der Mandant muss nun so konfiguriert werden, dass diese Rolle im Token enthalten ist. Nach erfolgreicher Authentifizierung generiert Keycloak das Token, welches Informationen über den Benutzer sowie gewährte Berechtigungen enthält. Die Anwendung nutzt das Token zur Identifikation des Benutzers und für entsprechende Aktionen basierend auf den Tokeninformationen. Dazu wird im Reiter „Client scopes“ zu „demo-client-dedicated“ navigiert und dort mit „Add predifined mapper“ ein neuer Token-Mapper für client roles definiert. Das Ganze wird mit „Add“ bestätigt. Ein Klick auf den neu angelegten Eintrag „client roles“ öffnet weitere Einstellungen. Hier wird für „Token Claim Name“ ein Wert festgelegt, z.B. roles , die Option „Add to ID tokenaktiviert und die Änderungen mit „Save“ bestätigt. Nun enthält das Token in der Anwendung über ein Attribut mit dem Schlüssel „roles“ alle Rollen des Benutzers.

Benutzerverwaltung

Um sich später in der Spring Boot Anwendung anmelden zu können, muss ein Benutzer definiert werden. Dazu wird ein neuer Benutzer im Realm angelegt. Das Formular zur Eingabe der Benutzerdaten wird über den Menüpunkt Users und den Button Add user aufgerufen. Im Rahmen dieses Leitfadens wird ein Benutzer mit dem Benutzernamen john.doe , dem Vor- und Nachnamen John Doe und der E-Mail-Adresse john.doe@example.com angelegt. Es ist nicht erforderlich, weitere Einstellungen zu ändern.

Für den neu angelegten Benutzer muss noch ein Passwort festgelegt werden. Dazu reicht es zunächst aus, im Benutzer unter dem Reiter Credentials und dem Button Set password ein neues, nicht temporäres Passwort zu setzen, z.B. password . Unter dem Reiter Role mapping wird dem Benutzer die zuvor angelegte Gruppe zugewiesen. Dazu wird auf Assign role geklickt und der Filter so eingestellt, dass die Mandantenrollen angezeigt werden. Anschließend wird die Rolle (demo-client) demo-role ausgewählt und mit Assign bestätigt.

Unter „http://localhost:8081/realms/demo-realm/account“ kann durch Anmelden mit dem angelegten Benutzer überprüft werden, ob dieser korrekt angelegt und konfiguriert wurde.

OAuth 2.0 Konfiguration in Spring Boot

Anpassen der Anwendungseigenschaften

Der erste Schritt bei der Konfiguration von OAuth 2.0 in der Anwendung ist die Anpassung der Datei application.yml. Dabei wird ein Provider demo-provider definiert, der auf den Realm verweist, und ein Client demo-client registriert:

Spring Security Konfiguration

Zusätzlich muss noch eine Konfiguration für Spring Security erstellt werden. Dazu wird eine neue Klasse SecurityConfiguration.kt erstellt, in der die Filterkette so konfiguriert wird, dass für den Endpunkt /private ein Benutzer mit OAuth 2.0 erfolgreich angemeldet sein muss. Mit der Syntax /private/** werden alle Endpunkte gesichert. Es müssen nicht alle einzeln angegeben werden.
Wurde die automatische Konfiguration von Spring Security per Annotation deaktiviert, wie wir es anfangs zu Testzwecken gemacht haben, muss sichergestellt werden, dass sie wieder aktiviert wird. Um dies zu erreichen, muss der Parameter aus der @SpringBootApplication() Annotation in der Datei DemoApplication.kt entfernt werden. Die Annotation selbst muss bestehen bleiben. Die Anwendung kann nun gestartet werden. Unter dem Endpunkt /public sollte keine Authentifizierung abgefragt werden und es wird lediglich „Hello from a public endpoint!“ angezeigt. Wird zum Endpunkt /private navigiert, so navigiert die Anwendung zunächst zum OAuth 2.0 Server. Hier kann eine Anmeldung mit dem Benutzer john.doe und dem Passwort password erfolgen. Anschließend sollte eine automatische Weiterleitung zurück zur urpsürnglichen Seite erfolgen. Nun wird der Text „Hello from a private endpoint!“ angezeigt.

Ausgabe der Informationen vom Token

Sobald ein Benutzer die Anwendung aufruft, wird in der Anwendung ein Benutzerobjekt erzeugt. Wenn der Benutzer sich nicht authentifiziert hat, z.B. am öffentlichen Endpunkt, wird der Benutzer als anonym behandelt. Sobald jedoch eine erfolgreiche Anmeldung über OAuth 2.0 erfolgt ist, wird ein entsprechendes Objekt mit dem erhaltenen Token erzeugt. Aus diesem Objekt können die Benutzerinformationen ausgelesen und für die Anwendung verwendet werden.

Ein wird nun ein weiterer Endpunkt zur Ausgabe dieser Daten hinzugefügt. Da alle Endpunkte bereits unter /private abgesichert sind, wird der neue Endpunkt unter „http://localhost:8080/private/user“ abgelegt. Die Benutzerinformationen können über den Kontext geladen werden. Dabei ist zu beachten, dass eine Konvertierung in einen OAuth2User vorgenommen wird. Die Umwandlung eines Principal-Objekts in ein OAuth2User-Objekt in Spring Boot ist sinnvoll, wenn erweiterte Benutzerinformationen aus dem OAuth 2.0-Token benötigt werden. Das OAuth2User-Objekt stellt standardisierte Methoden für den Zugriff auf diese Informationen bereit und erleichtert somit eine einheitliche Verarbeitung von OAuth 2.0-basierten Benutzerdaten in Spring-Boot-Anwendungen. Nach der Umwandlung kann auf die Attribute des Benutzers zugegriffen werden. In diesem Fall werden Name, E-Mail-Adresse und alle zugehörigen Rollen ausgegeben.

Die Anwendung kann neu gestartet und der neue Endpunkt getestet werden. Wird zum Endpunkt /private/user navigiert, findet eine erneute Authentifizierung statt. Möglicherweise geschieht dies automatisch, da das Cookie vom OAuth-Server noch gespeichert ist. Auf der Seite wird dann folgendes angezeigt:
Ausgabe auf http://localhost:8080/private/user

Entwicklungsperspektiven

Die Integration von Keycloak in Spring Boot ermöglicht eine effiziente und sichere Authentifizierung. Entwickler profitieren vom externen Authentifizierungsmanagement, können sich auf Kernfunktionen konzentrieren und Sicherheitsaspekte einfach implementieren. Die Flexibilität durch die Konfigurierbarkeit von Keycloak erlaubt die Anpassung an spezifische Anforderungen. Die Basis von Keycloak legt zudem den Grundstein für zukünftige Erweiterungen, ohne die Anwendungslogik stark verändern zu müssen. Die Flexibilität von Spring Boot ermöglicht es, auch andere OAuth 2.0 Server wie Azure, ADFS und mehr zu integrieren. Dadurch können Entwickler die Authentifizierungslösung an die spezifischen Anforderungen ihrer Anwendung anpassen.

Für weitere Details steht das GitHub Repository zur Verfügung, das alle im Artikel beschriebenen Schritte und Konfigurationen enthält, einschließlich eines vorkonfigurierten Keycloak Containers mit Docker.

Eine detaillierte Beschreibung der Funktionsweise von OAuth 2.0 und dem Zusammenspiel der verschiedenen Komponenten findet sich in dem verlinkten Artikel.

Sichern einer Spring Boot WebApp mit OAuth 2.0​

Authentifizierung ist der erste Schritt in jedem Sicherheitssystem. Es ist der Prozess mit dem die Identität eines Clients verifiziert wird. Ob der Client Zugriff auf bestimmte Ressourcen erhält, wird allerdings durch den Autorisierungsprozess festgestellt. In diesem Artikel werden wir eine API mit Spring Boot erstellen und das OAuth 2.0 Authentifizierungsprotokoll verwenden, um diese API abzusichern. Table of Contents Eingehende Erläuterungen und Definitionen OAuth 2.0 OAuth 2.0 (Open Authentication) ist ein

Weiterlesen »

Sichern einer Spring Boot WebApp mit OAuth 2.0​

Authentifizierung ist der erste Schritt in jedem Sicherheitssystem. Es ist der Prozess mit dem die Identität eines Clients verifiziert wird. Ob der Client Zugriff auf bestimmte Ressourcen erhält, wird allerdings durch den Autorisierungsprozess festgestellt. In

Weiterlesen »

Sichern einer Spring Boot WebApp mit OAuth 2.0​

Authentifizierung ist der erste Schritt in jedem Sicherheitssystem. Es ist der Prozess mit dem die Identität eines Clients verifiziert wird. Ob der Client Zugriff auf bestimmte Ressourcen erhält, wird allerdings durch den Autorisierungsprozess festgestellt. In diesem Artikel werden wir eine API mit Spring Boot erstellen und das OAuth 2.0 Authentifizierungsprotokoll verwenden, um diese API abzusichern. Table of Contents Eingehende Erläuterungen und Definitionen OAuth 2.0 OAuth 2.0 (Open Authentication) ist ein von der IETF entwickeltes Standardprotokoll, das die Authentifizierung und Autorisierung von

Weiterlesen »

Schreibe einen Kommentar