Keycloak Archive | INOTEQ GmbH

Automatisches Front-End-Testing einer OAuth 2.0 Spring-Boot Anwendungen

Alexander Kusmin — Thu, 08 Feb 2024 15:09:39 +0000

Automatisches Front-End-Testing einer OAuth 2.0 Spring-Boot Anwendungen

Dieser Beitrag vertieft die Thematik des automatischen Front-End-Testings einer OAuth 2.0 Spring Boot-Anwendung. Er fungiert als komplementäre Erweiterung zu unserem vorangegangenen Beitrag über Spring Boot mit OAuth 2.0 und Keycloak. Im Fokus stehen die Integration von Keycloak als zentraler OAuth 2.0 Dienst und die Rolle von Spring Boot als fundamentale Anwendungsplattform.

Ein kurzer Rückblick auf die wesentlichen Konzepte von OAuth 2.0 sowie die spezifische Bedeutung von Keycloak bietet einen soliden Ausgangspunkt. In unserem vorherigen Beitrag haben wir bereits die Integration von Spring Boot und Keycloak beleuchtet, um eine sichere OAuth 2.0-Authentifizierung zu gewährleisten. Falls Sie diesen Beitrag bisher nicht verfolgt haben, empfiehlt es sich, einen Blick darauf zu werfen, da der vorliegende Beitrag nahtlos auf den dort behandelten Grundlagen aufbaut.

Die Analyse konzentriert sich auf fortgeschrittene Aspekte des automatischen Front-End-Testings. Insbesondere wird die Erstellung einer GitLab Pipeline für automatische Tests auf bewährten Prinzipien von Keycloak und Spring Boot basierend erkundet. Das Ziel ist es, Ihnen Einblicke in die strategischen Schritte zu geben, um eine effiziente und zuverlässige Testumgebung zu schaffen, die sich nahtlos in Ihre Entwicklungsprozesse integrieren lässt.

Keycloak für die Testumgebung

Zum Testen der Spring Boot Anwendung ist eine Keycloak Konfiguration für die Testumgebung erforderlich. Später wird mithilfe von Testcontainers eine Keycloak-Instanz mit der gegebenen Konfiguration geladen, um die Authentifizierung in den Tests zu übernehmen. Zu diesem Zweck wird eine Import-Datei im JSON-Format benötigt. Ein einfacher Export der Konfiguration ist über die Keycloak-Benutzeroberfläche zwar möglich, allerdings werden aus Sicherheitsgründen die angelegten Benutzer nicht mit exportiert. Die Testumgebung wäre dann zwar in der Lage, sich mit dem OAuth 2.0 Server zu verbinden und normal zu starten, es stehen anschließend jedoch keine Benutzer für die Authentifizierung zur Verfügung.

Realm-Export mit Benutzern

Im Folgenden wird erklärt, wie man einen bereits vollständig konfigurierten Realm mit allen Benutzern exportiert, während der Keycloak-Server in einer Docker-Umgebung läuft. Im Repository zum letzten Beitrag findet sich bereits eine aus dem vorkonfigurierten Demo-Realm exportierte realm.json Datei, die hier wieder verwendet wird.

Folgender Befehl wird im Terminal des Systems ausgeführt:

docker exec -it keycloak-demo bash

Darüber gelangen wir in das Terminal innerhalb des Containers, auf dem der Keycloak-Server läuft. Dabei wird hier der Container keycloak-demo gewählt. Innerhalb des Containers wird dann folgender Befehl ausgeführt:

./opt/keycloak/bin/kc.sh export --dir /tmp/export --realm demo-realm --users realm_file

Damit exportieren wir die Realm-Konfiguration mit allen Benutzerdaten als demo-realm-realm.json in das Verzeichnis /tmp/export innerhalb des Containers. Mit dem Befehl exit gelangt man wieder in das Terminal des eigenen Systems zurück. Zuletzt wird die exportierte Datei mit dem folgendem Befehl aus dem Container herauskopiert.

docker cp keycloak-demo:/tmp/export/demo-realm-realm.json ~/Desktop/realm.json

In diesem Beispiel wird es einfach auf den Desktop kopiert und gleichzeitig in realm.json umbenannt, später wird diese aber im Spring Boot-Projekt gebraucht.

Sensible Daten Die exportierte Realm-Konfiguration kann sensible Daten wie Passwort-Hashes oder E-Mails enthalten. Aus diesem Grund sollte diese Variante ausschließlich für Entwicklungszwecke oder mit Testsysteme mit Testdaten verwendet werden.

Playwright Frontend Tests

Um die Benutzeroberfläche der Anwendung zu testen, wird das Testframework Playwright verwendet.

Im Vergleich zu dem bekannteren Selenium bietet Playwright einige Vorteile, wie zum Beispiel eine bessere Performance und weniger erforderlichen Boilerplate-Code beim Schreiben der Tests. Playwright bietet eine verbesserte Browser-Automation und unterstützt mehrere Browser. Außerdem gibt es eine native Unterstützung für den Headless-Modus, bessere Möglichkeiten zur Manipulation von Webseiten und eine einfache Verwendung mit Pipelines für automatische Tests.

Konfiguration

Für die Verwendung von Playwright für Tests muss die build.gradle angepasst werden. Zunächst sollte sichergestellt werden, dass es eine Test-Task für Gradle existiert und die benötigten Abhängigkeiten für Spring Boot Starter Tests als auch Playwright für die Testimplementierung angegeben sind, als auch die Abhängigkeiten für die Verwendung von OAuth 2.0 selbst.

build.gradle

dependencies {
    ...
    testImplementation 'org.springframework.boot:spring-boot-starter-test:3.2.2'
    testImplementation 'com.microsoft.playwright:playwright:1.41.1'
}

...

tasks.named('test') {
    useJUnitPlatform()
}

Eine Testklasse wird erstellt und für die Spring Boot Anwendung sowie für Playwright konfiguriert. Zunächst wird Playwright so konfiguriert, dass der automatische Testprozess beobachtet werden kann, um mögliche Fehler zu sichten. Später sollte diese Option wieder ausgestellt werden, da die Tests so wesentlich schneller laufen.

src/test/kotlin/DemoTest.kt

import ...

@SpringBootTest(
    classes = [DemoApplication::class],
    webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT
)
class DemoTest {
    companion object {
        // Playwright setup
        private var playwright: Playwright? = null
        private var browser: Browser? = null
        private var context: BrowserContext? = null
        private var page: Page? = null

        @JvmStatic
        @BeforeAll
        fun launchBrowser() {
            playwright = Playwright.create()
            
            browser = playwright?.chromium()?.launch(
                // Run playwright in headed mode with slow motion to see what's happening
                BrowserType.LaunchOptions().setHeadless(false).setSlowMo(100.0)
            )
        }

        @JvmStatic
        @AfterAll
        fun closeBrowser() {
            playwright?.close()
        }
    }

    @BeforeEach
    fun createContextAndPage() {
        context = browser?.newContext()
        page = context?.newPage()
    }

    @AfterEach
    fun closeContext() {
        context?.close()
    }
}

Damit kann Playwright nun für Tests verwendet werden.

Beispieltests

Wir halten uns bei diesem Beispiel an das Demo-Projekt aus dem letzten Beitrag und wollen die beiden Endpunkte /public und /private testen. Der /public Endpunkt ist immer aufrufbar, aber der /private Endpunkt ist erst aufrufbar, nachdem sich der Benutzer erfolgreich authentifiziert hat. Dafür müssen wir Playwright mitteilen, dass er nach dem Aufruf von /private auf eine Weiterleitung zum OAuth 2.0 Server warten soll, dort dann Benutzername und Passwort eingibt, bestätigt und zu guter Letzt wieder auf dem erwarteten Endpunkt /private landet.

src/test/kotlin/DemoTest.kt

@Test
fun publicEndpointTest() {
    page?.navigate("http://localhost:8080/public")
    assertThat(page?.locator("body")).hasText("Hello from a public endpoint!")
}

@Test
fun privateEndpointTest() {
    // Unable to access private endpoint without logging in and redirects to login page
    page?.navigate("http://localhost:8080/private")

    // Login with example user 'John Doe' by filling the login form and submitting it
    page?.fill("#username", "john.doe")
    page?.fill("#password", "password")
    page?.locator("input[type=submit]")?.click()
    // Wait for redirect to previously requested private endpoint
    page?.waitForURL("http://localhost:8080/private?continue")

    // Check for expected content on private endpoint
    assertThat(page?.locator("body")).hasText("Hello from a private endpoint!")
}

Um sicherzustellen, dass unsere Tests korrekt funktionieren, lassen wir den OAuth 2.0 Keycloak-Container im Hintergrund laufen und führen die Tests aus. Dabei wird ein neuer Chromium-Browser geöffnet, den Playwright manipuliert. Für einen kurzen Moment ist auch zu sehen, wie Playwright sich am OAuth 2.0 Server anmeldet.

Um die Auswirkungen von fehlendem OAuth 2.0 Zugriff zu zeigen, wird der Keycloak-Container gestoppt und die Tests erneut ausgeführt. Dadurch sollten die Tests fehlschlagen. Im nächsten Schritt wird der Zugriff wieder ermöglicht, indem bei den Tests ein Keycloak-Container erstellt und gestartet wird.

Keycloak Testcontainer

Zunächst benötigen wir die richtige Abhängigkeit, um einen Keycloak-Container für Tests zu starten. Dafür gibt es den Keycloak Testcontainer, eine spezielle Variante des Testcontainers, der für Keycloak angepasst wurde. Dazu wird die folgende Zeile in build.gradle eingefügt:

testImplementation 'com.github.dasniko:testcontainers-keycloak:3.2.0'

Wichtig ist, dass Docker auf Ihrem System läuft.

Die Testklasse wird so angepasst, dass unser gewünschter OAuth 2.0 Service wieder erreichbar ist, ohne dass wir den Container dafür erstellen und starten müssen. Dazu wird der Code wie folgt ergänzt:

src/test/kotlin/DemoTest.kt

companion object {
    // Start a Keycloak instance with an import file for the demo realm
    @JvmStatic
    private val keycloakContainer = KeycloakContainer().apply {
        withRealmImportFile("realm.json")
        portBindings = listOf("8081:8080")
        start()
    }

    // Register the Keycloak issuer URL as a dynamic property for the Spring Boot application
    @JvmStatic
    @DynamicPropertySource
    private fun registerResourceServerIssuerProperty(registry: DynamicPropertyRegistry) {
        registry.add("spring.security.oauth2.client.provider.demo-provider.issuer-uri") {
            "${keycloakContainer.authServerUrl}/realms/demo-realm"
        }
    }

    ...

    @JvmStatic
    @BeforeAll
    fun launchBrowser() {
        playwright = Playwright.create()
        browser = playwright?.chromium()?.launch() // Use headless mode
    }

   ...
}

Es wird ein Keycloak-Container definiert, der die zuvor exportierte realm.json importiert. Diese Datei muss sich dazu im Verzeichnis src/test/resources befinden. Zudem wird vor dem Start die Portbindung definiert.

Testcontainer werden immer mit einem zufälligen Port gestartet. Die Anwendung benötigt jedoch diesen Port, um den OAuth 2.0 Dienst richtig zu konfigurieren. Für diesen Zweck wird im Code die dynamische Eigenschaft für den OAuth 2.0-Dienst angepasst, indem wir die URL des Testcontainers einschließlich des Ports vor dem verwendeten Realm angeben.

Die Tests sind jetzt unabhängig von der lokalen Umgebung ausführbar. Während des Testprozesses wird ein neuer Container in Docker erstellt und nach Abschluss der Tests wieder gelöscht.

Es empfiehlt sich, Playwright wieder headless zu benutzen, da dadurch eine wesentlich bessere Performance erreicht wird. Das ist vor allem im nächsten Schritt wichtig.

GitLab Pipeline

Das Ziel war bisher, die Tests zu automatisieren und für eine GitLab-Pipeline ausführbar zu machen. Dafür ist es wichtig, dass der GitLab-Runner Docker-Container ausführen kann.

Playwright bietet ein Image an, das für die Zwecke dieses Projekts geeignet ist. Auf der Playwright-Website gibt es genauere Details zur kontinuierlichen Integration, einschließlich GitHub und anderen Plattformen. Auch für Testcontainers werden ausführliche Beispiele gezeict, wie man z.B. eine GitLab Pipeline mit Testcontainers konfiguriert. In unserem Fall orientieren wir uns an der Variante, die Docker-in-Docker verwendet.

Sobald die benötigten Anpassungen vorgenommen wurden, lassen sich mittels ./gradlew test die Tests ausführen.

gitlab-ci.yml

image: mcr.microsoft.com/playwright/java:v1.41.0-jammy

services:
  - name: docker:dind
    command: [ "--tls=false" ]

variables:
  DOCKER_HOST: "tcp://docker:2375"
  DOCKER_TLS_CERTDIR: ""
  DOCKER_DRIVER: overlay2

before_script:
  - GRADLE_USER_HOME="$(pwd)/.gradle"
  - export GRADLE_USER_HOME

stages:
  - test

tests:
  stage: test
  script:
    - ./gradlew test

Wie man nun sehen kann, läuft die Pipeline erfolgreich durch. Allerdings ist es erwähnenswert, dass sie einige Zeit dafür benötigt. Mit einer größeren Anzahl an Tests steigt auch die Zeit, die die Pipeline benötigt, um diese auszuführen. Dabei sei gesagt, dass die meiste Zeit für die Vorbereitung der Pipeline benötigt wird, einschließlich der größeren Abhängigkeiten wie dem Playwright Browser.

GitLab Runner

Running with gitlab-runner 14.7.0 (98daeee0)
  on gitlab-runner-01 y7AkGoZD
Preparing the "docker" executor 00:34
...
Preparing environment 00:00
...
Getting source from Git repository 00:02
...
Executing "step_script" stage of the job script 03:52
Using docker image sha256:df9599e540016f99fbcd1d862224ae9d1cf30df17fa5d367c969ee37cc060afb for mcr.microsoft.com/playwright/java:v1.41.0-jammy with digest mcr.microsoft.com/playwright/java@sha256:390fdf6801be59dd7bc6a3fad6344ae9d795b6585d102af293b57d61076d0824 ...
$ GRADLE_USER_HOME="$(pwd)/.gradle"
$ export GRADLE_USER_HOME
$ ./gradlew test
Downloading https://services.gradle.org/distributions/gradle-8.5-bin.zip
............10%.............20%............30%.............40%.............50%............60%.............70%.............80%............90%.............100%
Welcome to Gradle 8.5!
Here are the highlights of this release:
 - Support for running on Java 21
 - Faster first use with Kotlin DSL
 - Improved error and warning messages
For more details see https://docs.gradle.org/8.5/release-notes.html
Starting a Gradle Daemon (subsequent builds will be faster)
> Task :checkKotlinGradlePluginConfigurationErrors
> Task :processResources
> Task :processTestResources
> Task :compileKotlin
> Task :compileJava NO-SOURCE
> Task :classes
> Task :compileTestKotlin
> Task :compileTestJava NO-SOURCE
> Task :testClasses
> Task :test
OpenJDK 64-Bit Server VM warning: Sharing is only supported for boot loader classes because bootstrap classpath has been appended
Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.
You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.
For more on this, please refer to https://docs.gradle.org/8.5/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.
BUILD SUCCESSFUL in 3m 50s
6 actionable tasks: 6 executed
Cleaning up project directory and file based variables 00:01
Job succeeded

Fazit

Die vorgestellten Tests zeichnen sich durch ihre hohe Realitätsnähe aus, da sie auf einer dynamischen Keycloak-Testumgebung basieren. Dies vereinfacht die Entwicklung und trägt zur Sicherstellung einer zuverlässigen Authentifizierung bei. Jedoch ist es wichtig zu beachten, dass die GitLab Pipeline, aufgrund ihrer umfassenden Abhängigkeiten wie dem Playwright Browser, eine längere Ausführungszeit aufweisen kann. Trotz dieser potenziellen Einschränkung bieten die realitätsnahen Tests einen unschätzbaren Wert für die Entwicklung von sicheren und zuverlässigen OAuth 2.0 Spring Boot-Anwendungen.

Für weitere Details steht das GitHub Repository zur Verfügung, das alle im Artikel beschriebenen Schritte und Konfigurationen enthält.

Referenzierte Artikel

Integration von OAuth 2.0 in Spring Boot mit Keycloak

Alexander Kusmin 30. November 2023

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. Inhaltsverzeichnis Spring

Integration von OAuth 2.0 in Spring Boot mit Keycloak

Alexander Kusmin 30. November 2023

Integration von OAuth 2.0 in Spring Boot mit Keycloak

Alexander Kusmin 30. November 2023

Der Beitrag Automatisches Front-End-Testing einer OAuth 2.0 Spring-Boot Anwendungen erschien zuerst auf INOTEQ GmbH.

Integration von OAuth 2.0 in Spring Boot mit Keycloak

Alexander Kusmin — Thu, 30 Nov 2023 07:00:00 +0000

Integration von OAuth 2.0 in Spring Boot mit Keycloak

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

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.

src/main/kotlin/.../DemoApplication.kt

src/main/kotlin/.../DemoController.kt

src/main/kotlin/.../DemoApplication.kt

package com.example.demo

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration
import org.springframework.boot.runApplication

// Deaktivierung der default Authentifizierung von Spring Security
@SpringBootApplication(exclude = [SecurityAutoConfiguration::class])
class DemoApplication

fun main(args: Array) {
    runApplication(*args)
}

src/main/kotlin/.../DemoController.kt

package com.example.demo

import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
class DemoController {
    @RequestMapping("/")
    fun helloWorld() = "Hello World!"
}

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

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:

./src/main/kotlin/.../DemoController.kt

package com.example.demo

import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
class DemoController {
    @RequestMapping("/", "/public")
    fun publicEndpoint() = "Hello from a public endpoint!"

    @RequestMapping("/private")
    fun privateEndpoint() = "Hello from a private endpoint!"
}

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

Mögliche Herrausforderungen Bei der Integration von Spring Security und OAuth 2.0 können Herausforderungen wie Konfigurationskonflikte und unerwartetes Verhalten auftreten. Es ist ratsam sicherzustellen, dass die Versionen der verwendeten Abhängigkeiten konsistent sind. Eine Überprüfung der Logdateien auf mögliche Fehlermeldungen ist ratsam.

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

Ausgabe von Docker für Keycloak

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:

Schritt: Für den Client wird der Typ OpenID Connect ausgewählt und die Client-ID demo-client vergeben .
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.
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.

Schritt 1 - Erstellung eines Mandanten in Keycloak

Schritt 2 - Erstellung eines Mandanten in Keycloak

Schritt 3 - Erstellung eines Mandanten in Keycloak

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 token“ aktiviert 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.

Navigation zum Mandanten-Geltungsbereich

Ansicht zu Hinzufügen eines neuen Token-Mappers

Ausgewählter Token-Mapper für Mandanten-Rollen

Konfiguration des Token-Mappers

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:

./application.yml

spring:
  security:
    oauth2:
      client:
        provider:
          # provider name used for registration
          demo-provider:
            # Keycloak realm URL: "{keycloak-url}/realms/{realm-name}"
            issuer-uri: http://localhost:8081/realms/demo-realm
        registration:
          # client-id from Keycloak client configuration
          demo-client:
            # provider from above
            provider: demo-provider
            # client-id from Keycloak client configuration
            client-id: demo-client
            scope: openid
            # default redirect URI: "{baseUrl}/login/oauth2/code/{registrationId}"
            redirect-uri: http://localhost:8080/login/oauth2/code/demo-client

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.

./src/main/kotlin/.../SecurityConfiguration.kt

package com.example.demo

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.Customizer
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration
@EnableWebSecurity
class SecurityConfiguration {
    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain =
        http
            .authorizeHttpRequests {
                it
                    // Only allow authenticated users here
                    .requestMatchers("/private/**")
                    .fullyAuthenticated()
                    // Allow all other requests
                    .anyRequest()
                    .permitAll()
            }
            // Use OAuth 2.0 Login to handle authentication
            .oauth2Login(Customizer.withDefaults())
            .build()
}

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 auf http://localhost:8080/ bzw. http://localhost:8080/public

Anmeldung beim Versuch den privaten Endpunkt aufzurufen

Ausgabe auf http://localhost:8080/private, wenn sich erfolgreich angemeldet wurde

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.

./src/main/kotlin/.../DemoController.kt

...
@RequestMapping("/private/user")
    fun userEndpoint(): String {
        val user = SecurityContextHolder.getContext().authentication.principal as OAuth2User
        return "Name: ${user.attributes["name"]}, " +
            "Email: ${user.attributes["email"]}, " +
            "Roles: ${user.attributes["roles"]}"
    }
...

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:

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

Aymen Khalki 6. Mai 2021

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

Sichern einer Spring Boot WebApp mit OAuth 2.0

Aymen Khalki 6. Mai 2021

Sichern einer Spring Boot WebApp mit OAuth 2.0

Aymen Khalki 6. Mai 2021

Der Beitrag Integration von OAuth 2.0 in Spring Boot mit Keycloak erschien zuerst auf INOTEQ GmbH.