Bau deine eigene Test-App für OpenID Connect

Von /

In meiner Arbeit mit OpenID Connect (OIDC) bin ich oft auf die Herausforderung gestoßen, eine geeignete Test-App zu finden, mit der ich ID-Tokens und Access-Tokens analysieren und auswerten kann. Trotz langer Suche konnte ich keine App finden, die alle meine Anforderungen erfüllte. Schließlich stieß ich auf die Anwendung security-openid-connect-web-authentication-quickstart, die als Teil der Quarkus-Quickstarts frei verfügbar ist.

Auf Basis dieser App habe ich eine erweiterte Version erstellt, die:

  • Tokens ausgibt: Das ID- und Access-Token werden als JSON dargestellt
  • Rollen prüft: Die im ID-Token enthaltenen Rollen werden ausgewertet, um Zugriffsrechte anzuzeigen

Die Rollenprüfung dient hier lediglich als Beispiel. Mit etwas Programmierkenntnis kannst du die App leicht anpassen, um andere Testszenarien umzusetzen – etwa um spezifische Claims in ID- oder Access-Tokens auszuwerten. In diesem Blogpost zeige ich dir, wie du die App Schritt für Schritt einrichtest, erweiterst und nutzt.

Voraussetzungen

Nachfolgend die Liste der benötigten Anwendungen für die App sowie die konkret verwendeten Versionen:

  • Java 17
  • Maven 3.9.9 zum Bauen der Anwendung
  • Keycloak 26.01
  • Quarkus CLI

Schritt 1: Die App einrichten

1.1 Quarkus Quickstart herunterladen

Lade den Quarkus-Quickstart von GitHub herunter: Authentication in Web Applications Using OpenID Connect

1.2 Erweiterungen in der pom.xml

Ergänze die Datei pom.xml der Anwendung um die folgenden Abhängigkeiten:

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.13.0</version>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-oidc</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-resteasy</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-resteasy-jackson</artifactId>
</dependency>

Schritt 2: Keycloak konfigurieren

2.1 Client-Anwendung registrieren

  • Logge dich bei deinem Keycloak-Server ein und wähle deinen Realm.
  • Gehe zu Clients und erstelle eine neue Client-Anwendung:
    • Client ID: quarkus-app01
    • Client Authentication: On
    • Redirect URI: *
      Hinweis: Die Angabe von * als Redirect URI erlaubt, dass jede beliebige URL als Rückleitungsziel verwendet werden kann. Dies ist nützlich für Tests und Entwicklungszwecke, da es maximale Flexibilität bietet. In einer produktiven Umgebung sollte diese Einstellung aus Sicherheitsgründen nicht verwendet werden. Gib stattdessen die exakte URL deiner Anwendung an, z. B. https://meine-app.de/*
  • Speichere die Einstellungen und kopiere das Client Secret.

2.2 Rollen ins ID-Token einfügen

Damit die Rollen im ID-Token erscheinen, erstelle einen Mapper:

  • Gehe zu Clients → quarkus-app01 → Client Scopes → quarkus-app01-dedicated
  • Füge einen Mapper hinzu:
    • Name: realm-roles-mapper
    • Typ: User Realm Role
    • Token Claim Name: realm-roles
Abbildung: Mapper für die Anreicherung der Realm-Roles im ID-Token

Lege zumindest 2 Realm-Rollen user-role01 und admin-role01 an:

Schritt 3: Anwendung konfigurieren

Bearbeite die Datei application.properties in src/main/resources:

quarkus.oidc.auth-server-url=https://<keycloak-url>/realms/<realm-name>
quarkus.oidc.client-id=quarkus-app01
quarkus.oidc.credentials.secret=<dein-client-secret>
quarkus.oidc.application-type=web-app
quarkus.http.auth.permission.authenticated.paths=/*
quarkus.http.auth.permission.authenticated.policy=authenticated

Ersetze keycloak-url, realm.name und dein client secret durch deine spezifischen Werte.

Schritt 4: TokenResource.java einfügen

Die Datei TokenResource.java enthält die Logik zur Token-Ausgabe und Rollenprüfung. Du kannst sie hier herunterladen:

TokenResource.java

Kopiere und ersetze sie im Verzeichnis:

src/main/java/org/acme/security/openid/connect/web/authentication/

Schritt 5: App starten

  • Start die App im Entwicklermodus:
quarkus dev
  • Öffne deinen Browser und navigiere zu:
http://<App Domain-Name oder localhost>:8080/tokens

Du wirst nun zu Keycloak geleitet, loggst dich dort mit einem Nutzer ein und bist anschließend an der Applikation angemeldet:


Die App zeigt dir die Tokens (ID und Access) an, sowie die Berechtigungen basierend auf den Rollen im ID-Token. Du kannst sehen, ob ein Benutzer die Rollen user-role01 oder admin-role01 besitzt.

Weise einem Nutzer die Realm-Rolle user-role01 zu. Dadurch wird bei dir der user-access auf „true“ gesetzt und grün angezeigt:

Was macht der Code?

  • Injection der Tokens
    Die Tokens werden von Quarkus automatisch in die Anwendung injiziert. So kannst du sie direkt verwenden:
@Inject
@IdToken
JsonWebToken idToken;

@Inject
JsonWebToken accessToken;

@Inject
RefreshToken refreshToken;
  • Token-Dekodierung und Anzeige
    Die Methode decodeAndFormatToken zerlegt und formatiert die Tokens in lesbares JSON:
public String decodeAndFormatToken(JsonWebToken token) {
    String[] tokenParts = token.getRawToken().split("\\.");
    String header = new String(Base64.getUrlDecoder().decode(tokenParts[0]), StandardCharsets.UTF_8);
    String payload = new String(Base64.getUrlDecoder().decode(tokenParts[1]), StandardCharsets.UTF_8);
    return "<h3>Header:</h3><pre>" + header + "</pre><h3>Payload:</h3><pre>" + payload + "</pre>";
}
  • Rollenprüfung
    Die Methode hasUserRole prüft, ob ein Benutzer eine bestimmte Rolle besitzt:
public boolean hasUserRole(JsonWebToken idToken, String claim, String roleName) {
    String payload = new String(Base64.getUrlDecoder().decode(idToken.getRawToken().split("\\.")[1]), StandardCharsets.UTF_8);
    List<String> roles = objectMapper.convertValue(objectMapper.readTree(payload).get(claim), List.class);
    return roles.contains(roleName);
}
  • Dynamische HTML-Ausgabe
    Die Methode getTokens generiert eine HTML-Seite mit den Ergebnissen der Rollenprüfung und den dekodierten Tokens:
public String getTokens() {
    return "<html><body>"
        + (hasUserRole(idToken, "realm-roles", "user-role01") ? "<p>user-access: true</p>" : "<p>user-access: false</p>")
        + decodeAndFormatToken(idToken)
        + decodeAndFormatToken(accessToken)
        + "</body></html>";
}

Fazit

Diese OIDC-Test-App ist ein großartiges Werkzeug, um die Mechanik von Tokens besser zu verstehen und mit Rollen-basierten Berechtigungen zu arbeiten. Durch die einfache Konfiguration und den gut strukturierten Code ist sie leicht erweiterbar. Probiere es aus 🙂

Nach oben scrollen