Role-based access control in pure web

Dieses Tutorial zeigt Schritt für Schritt, wie man eine einfache Webanwendung erstellt, die mit Keycloak abgesichert ist. Das Ziel ist, am Ende eine eigene lauffähige Anwendung zu haben.

1. Theorie

1.1. Was ist RBAC?

RBAC steht für Role-Based Access Control. Es ist ein Konzept zur Zugriffskontrolle, bei dem Benutzer Rollen zugewiesen bekommen, und über diese Rollen Berechtigungen erhalten. Beispiel: Eine Rolle "admin" darf alles sehen, eine Rolle "user" nur bestimmte Bereiche.

Dieses Modell hilft, Systeme sicherer und übersichtlicher zu gestalten.

1.2. Was ist Pure Web Authentication?

Bei Pure Web handelt es sich um eine Architektur, bei der die gesamte Authentifizierung und Autorisierung clientseitig (also im Browser) erfolgt – ohne eigenes Backend. Die Anwendung verwendet ein sogenanntes public client in Keycloak sowie das offizielle keycloak-js-Script, um Benutzer zu authentifizieren.

1.2.1. Vorteile:

Schneller Login-Flow mit Weiterleitung zu Keycloak
Token-Auswertung im Browser (z. B. für Rollen)

1.2.2. Nachteile:

Nur für einfache Anwendungsfälle geeignet
Sicherheit muss im Frontend sorgfältig bedacht werden

2. Vorbereitung

2.1. Voraussetzungen

Docker & Docker Compose
Eine IDE (z.B. IntelliJ)
Node.js (um das Frontend lokal zu hosten)
Browser (Firefox, Chrome, etc.)

2.2. Projektstruktur

(Beispiel:)

keycloak-rbac-pureweb-demo/
├── frontend/               → HTML/CSS/JS-Webseite
├── keycloak/               → Docker-Setup für Keycloak

3. Keycloak lokal starten

Öffne ein Terminal, wechsle in den Ordner keycloak/ und erstelle docker-compose.yaml:

version: '3'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:24.0.1
    container_name: keycloak
    ports:
      - "8080:8080"
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    command: start-dev

Starte nun den Container über das Terminal:

cd keycloak
docker compose up -d

Rufe im Browser http://localhost:8080 auf. Klicke auf „Administration Console“ und logge dich ein mit:

Benutzername: admin
Passwort: admin

4. Keycloak konfigurieren

4.1. Realm erstellen

Ein Realm ist wie ein Projekt oder eine Umgebung. Erstelle einen neuen Realm mit dem Namen rbac-demo.

4.2. Client anlegen

Ein Client ist die Anwendung, die sich bei Keycloak anmeldet – in unserem Fall das Web-Frontend.

Gib folgendes ein:

Client ID: frontend-client
Client Type: Public
Name: Frontend Demo
Root URL: leer lassen

Anschließend unter „Settings“ folgende Werte setzen und speichern:

Valid Redirect URIs: http://localhost:3000/* (URL, auf der das Frontend gehosted wird)
Web Origins: *

Nicht vergessen, auf "Save" zu klicken!

4.3. Rollen anlegen

Wechsle zu „Realm Roles“ und lege zwei Rollen an:

admin
user

4.4. Benutzer erstellen

Zwei Benutzer anlegen (Passwort unter "Credentials"):

Benutzername: admin, Passwort z.B. admin
Benutzername: student, Passwort z.B. student

Klicke auf „Set Password“ und deaktiviere „Temporary“, damit du dich direkt einloggen kannst.

Unter „Role Mappings“ können den Benutzern entsprechende Rollen zugewiesen werden.

5. Frontend bauen

Da der Keycloak-Server nun fertig ist, kann das Frontend erstellt werden. Erstelle im frontend/ - Ordner folgende Dateien:

5.1. index.html

<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="UTF-8" />
  <title>Keycloak RBAC Demo</title>
  <link rel="stylesheet" href="styles.css" />
  <script src="https://cdn.jsdelivr.net/npm/keycloak-js@24.0.1/dist/keycloak.min.js"></script>
  <script defer src="app.js"></script>
</head>
<body>
  <div class="container">
    <h1>RBAC-Demo mit Keycloak</h1>
    <div class="userinfo">
      <p><strong>Benutzer:</strong> <span id="username">-</span></p>
      <p><strong>Rollen:</strong> <span id="roles">-</span></p>
    </div>

    <div id="admin-section" class="card hidden">
      <h2>Admin-Bereich</h2>
      <p>Nur für Admins sichtbar.</p>
    </div>

    <div id="user-section" class="card hidden">
      <h2>Benutzerbereich</h2>
      <p>Nur für normale Benutzer sichtbar.</p>
    </div>

    <button id="logout-btn" class="logout-btn hidden">Logout</button>
  </div>
</body>
</html>

5.2. styles.css

Der Style ist natürlich nicht unbedingt notwendig

body {
  font-family: sans-serif;
  background: #f5f5f5;
  padding: 2rem;
}
.container {
  max-width: 600px;
  margin: auto;
  background: white;
  padding: 2rem;
  border-radius: 12px;
  box-shadow: 0 5px 15px rgba(0,0,0,0.1);
}
.card {
  background: #e3fce3;
  padding: 1rem;
  margin-bottom: 1rem;
  border-left: 4px solid green;
}
.logout-btn {
  background: crimson;
  color: white;
  padding: 0.6rem 1rem;
  border: none;
  border-radius: 6px;
  cursor: pointer;
}
.hidden {
  display: none;
}

5.3. app.js

const keycloak = new Keycloak({
  url: "http://localhost:8080",
  realm: "rbac-demo",
  clientId: "frontend-client"
});

keycloak.init({ onLoad: 'login-required' }).then(authenticated => {
  if (!authenticated) return;

  const token = keycloak.tokenParsed;
  const roles = token.realm_access?.roles || [];

  document.getElementById("username").textContent = token.preferred_username;
  document.getElementById("roles").textContent = roles.join(", ");

  if (roles.includes("admin")) {
    document.getElementById("admin-section").classList.remove("hidden");
  }

  if (roles.includes("user")) {
    document.getElementById("user-section").classList.remove("hidden");
  }

  document.getElementById("logout-btn").classList.remove("hidden");
  document.getElementById("logout-btn").addEventListener("click", () => {
    keycloak.logout({ redirectUri: window.location.href });
  });
});

6. Anwendung starten

6.1. Mit Node.js

cd frontend
npx serve .

Das Frontend läuft nun unter http://localhost:3000 im Browser.

Man wird automatisch zu Keycloak weitergeleitet, muss sich einloggen und seine Daten vervollständigen.

Je nach Rolle erscheinen unterschiedliche Inhalte.

Student:

Admin:

7. Zusammenfassung

Im Tutorial wurde gezeigt, wie man:

Keycloak mit Docker lokal startet
Benutzer, Rollen und Clients einrichtet
eine einfache Webanwendung mit Keycloak absichert
rollenbasierten Zugriff direkt im Browser umsetzt

Dieses Wissen ist eine wichtige Grundlage für moderne Webentwicklung mit Login, SSO und RBAC.