AuthPractice

    Keycloak Tutorial: Die meisten Projekte brauchen es nicht (noch nicht)

    Die meisten Keycloak-Tutorials setzen voraus, dass man es braucht. Stimmt meistens nicht. Authentication wird gebraucht, klar. Aber für die meisten Projekte ist Keycloak implementieren wie aus einem Feuerwehrschlauch trinken, wenn eigentlich nur ein Glas Wasser nötig wäre.

    Falls Keycloak her muss: So funktioniert Keycloak SSO in 30 Minuten. Kleine Warnung: Die Dev-Umgebung läuft schnell, aber bis es in Production richtig funktioniert, vergehen 12 bis 14 Wochen. Das ist kein Keycloak-Problem, das ist IAM-Realität.

    Der Punkt ist: Bei Keycloak geht's eigentlich nicht um Authentication. Es geht um Single Sign-On (SSO) und komplettes User-Lifecycle-Management. Wenn jemand ins Unternehmen kommt, die Abteilung wechselt oder geht. Wenn BigCorp die Firma übernimmt und plötzlich 5.000 Mitarbeiter Zugriff brauchen. Wenn der Auditor fragt: "Wer hatte wann Zugriff worauf und warum?"

    Mit einfacheren Frameworks wie Passport.js, NextAuth oder Devise wird die Frage beantwortet: "Wie loggen sich User ein?"

    Mit Keycloak beschäftigt man sich mit etwas Größerem: "Wie wird Identität über die gesamte Organisation gemanagt?"

    Das ist eine fundamental andere Herausforderung. Die meisten Entwickler machen diese Erfahrung auf die harte Tour - sie implementieren Keycloaks technische Features, ohne die Business-Probleme zu verstehen, die diese lösen.

    Phase 1: 50 User vorhanden (Keycloak unnötig)

    Die Anforderungen:

    • User loggen sich mit Email/Passwort ein
    • Basis Session-Management
    • Passwort-Reset per Email

    Implementierungszeit mit Passport.js: 2 Stunden
    Implementierungszeit mit Keycloak: 2 Wochen

    Hier das komplette Authentication-System:

    javascript
    // Komplette Authentication in 47 Zeilen const passport = require('passport'); const LocalStrategy = require('passport-local').Strategy; const bcrypt = require('bcrypt'); // Mehr wird nicht gebraucht für Basic Auth passport.use(new LocalStrategy({ usernameField: 'email' }, async (email, password, done) => { const user = await User.findOne({ email }); if (!user) return done(null, false); const valid = await bcrypt.compare(password, user.password); if (!valid) return done(null, false); return done(null, user); } )); // Login Endpoint app.post('/login', passport.authenticate('local'), (req, res) => { res.json({ user: req.user }); }); // Logout app.post('/logout', (req, res) => { req.logout(); res.json({ message: 'Logged out' }); }); // Passwort-Reset app.post('/reset-password', async (req, res) => { const token = crypto.randomBytes(20).toString('hex'); await User.updateOne( { email: req.body.email }, { resetToken: token, resetExpires: Date.now() + 3600000 } ); await sendEmail(req.body.email, `Reset link: ${process.env.URL}/reset/${token}`); res.json({ message: 'Email sent' }); }); // Geschützte Route app.get('/dashboard', ensureAuthenticated, (req, res) => { res.json({ data: 'Secret data', user: req.user }); }); function ensureAuthenticated(req, res, next) { if (req.isAuthenticated()) return next(); res.status(401).json({ error: 'Not authenticated' }); }

    Fertig. Der CEO ist zufrieden. User können sich einloggen. Keycloak bleibt uninstalliert.

    Aber was ist mit JWT Tokens?

    Werden noch nicht gebraucht. Sessions funktionieren prima für eine einzelne Anwendung. JWTs werden erst bei mehreren Services nötig:

    javascript
    // JWTs werden bei mehreren Services gebraucht // Service A (Haupt-App) - gibt Tokens aus app.post('/login', async (req, res) => { const user = await authenticateUser(req.body); const token = jwt.sign( { id: user.id, email: user.email }, process.env.JWT_SECRET, { expiresIn: '1h' } ); res.json({ token }); }); // Service B (API) - validiert Tokens app.get('/api/data', (req, res) => { const token = req.headers.authorization?.split(' ')[1]; try { const user = jwt.verify(token, process.env.JWT_SECRET); res.json({ data: 'Secret data for ' + user.email }); } catch (err) { res.status(401).json({ error: 'Invalid token' }); } });

    Immer noch nur 20 Zeilen. Immer noch kein Keycloak nötig.

    Phase 2: Google Login kommt dazu (Keycloak immer noch unnötig)

    Neue Anforderung: "Unsere User wollen sich mit Google einloggen"

    Zeit zum Hinzufügen mit Passport.js: 1 Stunde
    Zeit zum Hinzufügen mit Keycloak: 1 Tag     (nachdem Realm-Konfiguration verstanden wurde)

    javascript
    // Google Login in 15 Zeilen hinzufügen const GoogleStrategy = require('passport-google-oauth20').Strategy; passport.use(new GoogleStrategy({ clientID: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET, callbackURL: "/auth/google/callback" }, async (accessToken, refreshToken, profile, done) => { let user = await User.findOne({ googleId: profile.id }); if (!user) { user = await User.create({ googleId: profile.id, email: profile.emails[0].value, name: profile.displayName }); } return done(null, user); } )); app.get('/auth/google', passport.authenticate('google', { scope: ['profile', 'email'] }) ); app.get('/auth/google/callback', passport.authenticate('google'), (req, res) => res.redirect('/dashboard') );

    Jetzt läuft sowohl Email/Passwort als auch Google Login. Gesamter Code: ~70 Zeilen. Keycloak würde Docker, Realm-Setup, Client-Konfiguration und Verständnis von OAuth2-Flows erfordern, die noch gar nicht verstanden werden müssen.

    Phase 3: Partner API-Zugriff - Die versteckte Komplexität

    Neue Anforderung: "Partner brauchen API-Zugriff mit eigenen Keys"

    Hier wird's interessant. Es geht nicht mehr nur um User-Authentication - Service Accounts, API Keys, Rate Limiting und Audit Trails müssen gemanagt werden.

    javascript
    // Was einfach anfängt... app.post('/api/authenticate', (req, res) => { const apiKey = req.headers['x-api-key']; const client = await Client.findOne({ apiKey }); if (!client) return res.status(401).json({ error: 'Invalid API key' }); res.json({ token: generateToken(client) }); }); // ...wird schnell zum Albtraum // - Wie werden API Keys rotiert? // - Wie wird Rate Limiting per Client gemacht? // - Wie wird auditiert, welcher Client auf was zugegriffen hat? // - Wie wird Zugriff sofort widerrufen? // - Wie wird OAuth2 Client Credentials Flow implementiert? // - Wie werden Scopes per Client gemanagt?

    Mit einfacheren Tools wird ein eigener OAuth2-Server gebaut. Mit Keycloak sind Service Accounts First-Class Citizens:

    bash
    # Service Account Client in Keycloak erstellen docker exec keycloak /opt/keycloak/bin/kcadm.sh create clients -r myrealm \ -s clientId=partner-api \ -s enabled=true \ -s serviceAccountsEnabled=true \ -s publicClient=false \ -s secret=partner-secret \ -s 'defaultClientScopes=["api-read", "api-write"]' # Partner bekommt Token über Client Credentials curl -X POST http://localhost:8080/realms/myrealm/protocol/openid-connect/token \ -d "grant_type=client_credentials" \ -d "client_id=partner-api" \ -d "client_secret=partner-secret"

    Jetzt existiert ein ordentlicher Client Credentials Flow, automatisches Rate Limiting, komplette Audit Trails, sofortiger Widerruf und Scope-Management. Das selbst zu bauen bedeutet Monate Arbeit und Sicherheitslücken.

    Phase 4: Mehrere Anwendungen - Der SSO-Wendepunkt

    Neue Anforderung: "Eine Mobile App und ein Admin Panel werden gebaut. User sollen sich einmal einloggen und auf alles zugreifen können."

    Jetzt beginnt SSO-Territorium. Mit Passport.js wird's unschön:

    javascript
    // Option 1: Shared Session Store (kein echtes SSO) const RedisStore = require('connect-redis')(session); const redis = require('redis'); const redisClient = redis.createClient(); // App 1, App 2, App 3 nutzen denselben Session Store app.use(session({ store: new RedisStore({ client: redisClient }), secret: 'shared-secret', cookie: { domain: '.yourcompany.com' } // Kritisch fürs Teilen })); // Problem: Funktioniert nicht für Mobile Apps // Problem: Funktioniert nicht über verschiedene Domains // Problem: Nicht wirklich SSO, nur geteilte Sessions

    oder

    javascript
    // Option 2: Eigenen OAuth2-Server bauen (keine gute Idee) const oauth2orize = require('oauth2orize'); const server = oauth2orize.createServer(); // 200+ Zeilen Code für ordentliche OAuth2-Implementierung // Tokens, Refresh Tokens, Authorization Codes, PKCE... // Sicherheitslücken vorprogrammiert

    Hier kippt die Waage. Wenn echtes SSO über mehrere Anwendungen gebraucht wird, besonders mit Mobile Apps, macht Keycloak Sinn. Aber selbst hier: Wochen vergehen, bis es production-ready ist. Wer an diesem Punkt ist, sollte mit Keycloak SSO experimentieren, um die Komplexität zu verstehen. Es öffnet Augen.

    Phase 5: Enterprise-Integration - Willkommen in der Champions League

    Neue Anforderung: "BigCorp will, dass ihre 5.000 Mitarbeiter sich mit Windows-Credentials einloggen"

    Mit einfacheren Frameworks wie Passport.js stehen Wochen custom LDAP-Code bevor. Mit Keycloak ist es Konfiguration - aber hier wird's interessant: Es ist nicht mehr nur technische Konfiguration. Identity-Lifecycle wird gemanagt.

    Wenn Sarah bei BigCorp vom Vertrieb in die Entwicklung wechselt:

    • Ihre Active Directory Gruppen ändern sich
    • Ihre Anwendungsberechtigungen müssen aktualisiert werden
    • Ihr Zugriff auf Kundendaten sollte entzogen werden
    • Ihr Zugriff auf GitHub sollte gewährt werden
    • Der Audit Trail muss die Änderung zeigen

    Das ist der "Mover" im Joiner/Mover/Leaver-Prozess. Passport.js hat nicht mal Konzepte dafür. Keycloak schon, weil es keine Authentication-Library ist - es ist eine IAM-Plattform.

    Aber es kommt noch besser: BigCorp wird auch fragen "Ist das System DSGVO-konform?"

    Hier etwas, was niemand erwähnt: Keycloak out-of-the-box ist NICHT DSGVO-konform. Aber es KANN konform gemacht werden - Keycloak liefert alle Bausteine, sie müssen nur richtig zusammengesetzt werden.

    Und seien wir ehrlich: In Deutschland ist die DSGVO mittlerweile zu einem eigenen Monster herangewachsen. Was als sinnvoller Datenschutz gedacht war, wurde durch typisch deutsche Gründlichkeit zu einem bürokratischen Koloss. Aber genau diese Liebe zur Regulation macht Keycloaks Flexibilität so wertvoll - jede noch so spezifische Compliance-Anforderung kann konfiguriert werden.

    Die offensichtlichsten Anforderungen, die Konfiguration brauchen:

    Informationspflicht (DSGVO Art. 13): Bevor Daten gesammelt werden, muss über die Datenverarbeitung informiert werden. Keycloaks Standard-Registrierungsflow sammelt erst, informiert nie. User geben Email, Username, persönliche Daten ein - alles wird sofort gespeichert ohne Datenschutzhinweis.

    Explizite Einwilligung (DSGVO Art. 6(1)(a)): User müssen explizit der Datenverarbeitung zustimmen, bevor der Account aktiviert wird. Keycloaks Standard aktiviert Accounts sofort nach der Registrierung. Keine Einwilligungs-Checkbox. Kein "Ich stimme den Bedingungen zu." Die Daten sind bereits gespeichert.

    Und das ist nur der Anfang. Passwort-Reset-Emails enthalten personenbezogene Daten ohne Aufbewahrungskontrollen. Audit Logs könnten gegen Datenaufbewahrungsrichtlinien verstoßen. Kein eingebauter Workflow für das Recht auf Vergessenwerden. Keine Datenportabilitäts-Exporte. Alles braucht custom Konfiguration.

    Warum ist das nicht vorkonfiguriert? Die vernünftige Antwort: Jede Firmen-DSGVO-Implementierung ist anders - was für ein deutsches B2B-SaaS funktioniert, funktioniert nicht für eine französische Consumer-App. Keycloak bietet die Flexibilität, spezifische Anforderungen umzusetzen, statt eine Interpretation der DSGVO aufzuzwingen.

    Für Enterprise-Kunden in Europa ist das nicht optional - es ist Grundvoraussetzung. Und ja, manchmal fühlt es sich an, als würde man ein Compliance-Theater aufführen. Aber dieses Theater entscheidet über Millionen-Deals.

    Phase 6: Wenn Compliance über Leben und Tod entscheidet

    Neue Anforderung: "Es muss nachvollziehbar sein, wer wann auf was zugegriffen hat, MFA für Admins implementiert werden, Accounts nach 90 Tagen Inaktivität automatisch deaktiviert werden und Auditoren bewiesen werden, dass gekündigte Mitarbeiter auf nichts zugreifen können."

    Es werden keine technischen Probleme mehr gelöst. Es werden Business- und Compliance-Probleme gelöst:

    • Joiner: Neuer Mitarbeiter fängt Montag an. Braucht genau den richtigen Zugriff am ersten Tag.
    • Mover: Mitarbeiter wechselt die Rolle. Alter Zugriff entzogen, neuer gewährt, Audit Trail erstellt.
    • Leaver: Mitarbeiter gekündigt. Zugriff überall innerhalb einer Stunde entfernt. Beweis für Auditoren.

    Wer das mit Passport.js implementiert, baut sein eigenes IAM-System. Schlecht.

    Hier der Extremfall, der zeigt, warum ausgereiftes IAM wichtig ist:

    Während eines Herznotfalls braucht ein Notarzt sofortigen Zugriff auf jede Patientenakte. Normale HIPAA-Kontrollen könnten Leben kosten. Aber jeder Notfallzugriff muss einen Audit Trail erstellen, Review-Workflows auslösen und Compliance-Reports innerhalb von 24 Stunden generieren.

    Das nennt sich "Break-Glass Access" - die Fähigkeit, normale Berechtigungen in Notfällen zu überschreiben und dabei vollständige Rechenschaftspflicht zu wahren. Mit Keycloak implementierbar. Mit einfacheren Tools wird mit Leben und Klagen gespielt. Die Komplexität ist keine Bürokratie - sie ist notwendig.

    Das selbst zu bauen ist nicht nur technisch anspruchsvoll - es ist ethisch fragwürdig. Wenn IAM-Fehler Leben oder Millionen an Compliance-Strafen kosten können, wird ein kampferprobtes System gebraucht.

    Die Realität des Keycloak-Lernens

    Was niemand sagt: Keycloak hat eine der steilsten Lernkurven in der modernen Tech-Welt. Nicht weil es schlecht designed ist, sondern weil nicht nur ein Tool gelernt wird - eine ganze Domäne (IAM) wird gelernt, die die meisten Entwickler nie richtig studieren.

    Der typische Weg: Woche 1 fühlt sich einfach an (Docker läuft, User loggen sich ein). Woche 3 ist pure Verwirrung (redirect_uri Fehler, CORS-Failures, Tokens laufen zufällig ab). Nach Monat 3 werden vielleicht die Basics verstanden. Nach 6 Monaten fühlt man sich wohl. Echte Expertise? Dauert Jahre und beinhaltet, Business-Anforderungen genauso zu verstehen wie technische Konfiguration.

    Klartext: Wenn nur Authentication gebraucht wird, lohnt sich diese Lernkurve nicht. Beim Aufbau von richtigem Identity Management ist sie unvermeidbar.

    Drei Wege, wie Firmen diese Lektion schmerzlich lernen

    Falls eines dieser Szenarien bekannt vorkommt - das ist normal:

    "SSO kommt später" - Mit Passport.js gebaut, weil's schnell ging. Zwei Jahre später braucht der Enterprise-Kunde SAML. Team schätzt 4 Wochen (mit Puffer). Sechs Monate später immer noch am Auth-Layer-Rebuild, SAML unberührt. Kunde unterschreibt bei der Konkurrenz. 2 Millionen Euro Expansion weg.

    "Gleich richtig machen" - 50 User, aber der CTO besteht auf "enterprise-ready" und "für Scale bauen". Typisch deutsche Gründlichkeit - alles muss perfekt sein, bevor auch nur eine Zeile produktiver Code geschrieben wird. Drei Monate SAML-Konfigurationen debuggen, während die Konkurrenz wöchentlich Features shipped. Sie kommen zuerst auf den Markt. Ein Aufholen war unmöglich.

    "Basic Auth reicht erstmal" - Kein MFA, keine Audit Logs, Sessions laufen nie ab. Datenleck durch Passwort-Wiederverwendung. Strafen, Kundenflucht, Notverkauf. Alles vermeidbar gewesen.

    Das Muster ist klar: Keycloak zu früh nutzen verschwendet Monate. Zu spät nutzen kostet Millionen. Der optimale Zeitpunkt? Normalerweise irgendwo zwischen Phase 3 und 4 - wenn Service Accounts gemanagt werden müssen oder echtes SSO gebraucht wird.

    Das Entscheidungs-Framework

    Nach Auth-Implementierung für 50+ Projekte wurde Folgendes gelernt:

    Einfachere Frameworks nutzen (Passport/NextAuth/Devise) wenn:

    • Einzelne Anwendung vorhanden
    • < 100 User
    • Basic Login (Email/Passwort + eventuell Google)
    • Keine Enterprise-Integration
    • Keine Compliance-Anforderungen
    • Technisches Team handled Auth
    • Gelöst wird: "Wie loggen sich User ein?"

    Keycloak erwägen wenn:

    • Mehrere Anwendungen existieren (echtes SSO nötig)
    • Enterprise-Integration ansteht (LDAP/AD)
    • Compliance-Anforderungen vorhanden
    • 1000+ User
    • HR muss Zugriff managen
    • Gelöst wird: "Wie wird Identity-Lifecycle gemanagt?"

    Definitiv Keycloak nutzen wenn:

    • M&A-Aktivität (mehrere Firmen integrieren)
    • Mehrere Protokolle nötig (OIDC + SAML)
    • Regulierte Industrie (Finanz, Gesundheitswesen)
    • B2B SaaS mit Enterprise-Kunden
    • Gelöst wird: "Wie wird Compliance bewiesen?"

    Auth0/Okta erwägen wenn:

    • Es muss HEUTE funktionieren
    • Kein DevOps-Team vorhanden
    • 1000+€/Monat sind akzeptabel
    • US-Datenhaltung ist OK
    • Standard-Flows reichen aus
    • Gelöst wird: "Das Problem soll nicht selbst gelöst werden"

    Bei komplexen custom Anforderungen (wie diesem Notaufnahme Break-Glass-Szenario) wird Keycloaks Open-Source-Natur entscheidend. Custom Authenticators können geschrieben, Flows modifiziert, spezifische Audit-Anforderungen hinzugefügt werden. Bei kommerziellen Lösungen bedeuten custom Anforderungen 50.000-250.000€ nur zum Bauen, plus 30.000-80.000€/Jahr laufend (wirklich) oder "sorry, wird nicht unterstützt."

    Warnsignale beim Herauswachsen aus Simple Auth

    Diese Warnzeichen zeigen, dass ein Upgrade von Simple Auth zu Keycloak ansteht:

    • API-Partner fragen nach OAuth2 Client Credentials Flow
    • Bei der zweiten Anwendung kommt der Gedanke "User sollten sich nicht zweimal einloggen müssen"
    • Sales verliert Deals, weil "SAML gebraucht wird"
    • API Keys werden in einer Datenbank-Spalte namens "api_key" gespeichert
    • Der Auditor fragt nach einem Zugriffsbericht und eine SQL-Query wird ausgeführt
    • Ein eigenes "Admin Panel" für User-Management wurde gebaut
    • Session-Management-Code wird zur komplexen State Machine
    • Jemand fragt nach "Service Accounts" und die Bedeutung ist unklar

    Bei 2-3 dieser Zeichen sollte die Migration geplant werden. Bei 4+ besteht bereits Rückstand.

    Die Wissenslücke, über die niemand spricht

    Faszinierend: Jedes Keycloak-Feature kann gemeistert werden - Realms, Clients, Flows, Mappers, Federations - und trotzdem wird bei der IAM-Implementierung spektakulär gescheitert. Warum? Keycloak-Dokumentation zeigt, WELCHE Buttons geklickt werden, nicht WANN oder WARUM.

    Echte Expertise bedeutet nicht zu wissen, dass Keycloak "Authentication Flows" hat. Es bedeutet zu wissen, dass Break-Glass-Notfallzugriff einen custom Authentication Flow mit Step-up-Authentication, zeitlich begrenzter Erhöhung und automatisierten Audit-Triggern braucht. Die Dokumentation lehrt das nicht. Stack Overflow auch nicht.

    Diese Lücke zwischen technischen Features und Business-Anforderungen lässt die meisten IAM-Projekte scheitern. User Federation wird perfekt implementiert, aber niemand realisiert, dass der Joiner/Mover/Leaver-Lifecycle gehandhabt werden muss. SAML wird wunderschön konfiguriert, aber niemand weiß, dass Enterprise-Kunden Session-Timeout nach 15 Minuten Inaktivität erwarten, nicht 15 Minuten gesamt. Audit-Events werden eingerichtet, aber das Format passt nicht zu dem, was Compliance-Auditoren tatsächlich brauchen.

    AuthPractice wurde als IAM-Simulator gebaut, speziell um diese Lücke zu überbrücken. Kein weiteres "hier klicken um Realm zu konfigurieren" Tutorial, sondern Szenarien, die zeigen, warum jedes Feature existiert. Der panische Freitag, wenn der Zugriff eines gekündigten Mitarbeiters überall widerrufen werden muss. Die Audit-Anfrage, die Beweise für Zugriffskontrollen braucht. Die Übernahme, bei der 2.000 neue User bis Montagmorgen präzise abgestuften Zugriff brauchen.

    Am Ende geht es bei IAM-Expertise nicht darum, Keycloak, Auth0 oder Okta zu kennen. Es geht darum, Identity-Patterns zu verstehen, die über jedes spezifische Tool hinausgehen. Sobald verstanden wird, warum Break-Glass-Zugriff existiert und was dafür benötigt wird, um ihn richtig zu unterstützen, wird die Umsetzung in jedem System unkompliziert. Nach der Erfahrung, dass ein gekündigter Mitarbeiter Monate später immer noch auf Kundendaten zugreift, werden Identity-Systeme nie wieder gleich designed.

    Schnelltest bei Unsicherheit: Wer die Passport.js-Beispiele versteht, aber bei 'Break-Glass Access' abschaltet, sollte bei Passport bleiben. Zeit für Keycloak ist gekommen, wenn Compliance-Anforderungen den Schlaf rauben, nicht technische Herausforderungen.