Keycloak einrichten

Keycloak ist als OIDC-Identity-Provider vollständig unterstützt. Diese Anleitung führt dich durch die Einrichtung — vom Anlegen des Realm-Clients bis zum Gruppen-Mapping in LIVCK.

Übersicht

Keycloak kann Gruppenzugehörigkeiten auf zwei Wegen im Token liefern:

Wir empfehlen Gruppen, weil sie im Standard-Keycloak-Mapper direkt als flaches Array im Token landen und sich sauber mappen lassen. Realm-Rollen liegen verschachtelt in realm_access.roles und brauchen einen eigenen Protocol Mapper, damit LIVCK sie als Groups-Claim auslesen kann.

Weg A: Gruppen (empfohlen)

1. Realm (falls nötig) anlegen

Keycloak organisiert alles in Realms. Pro Organisation empfiehlt sich ein eigener Realm.

1. Keycloak Admin Console → Menü oben links → Create Realm
2. Realm name: z.B. livck
3. → Create

2. Client registrieren

1. Realm livck → Clients → Create client
2. Client type: OpenID Connect
3. Client ID: z.B. livck
4. → Next
5. Authentication flow:
   • Client authentication: ☑ ON (damit wird ein Client-Secret erzeugt — zwingend für LIVCK)
   • Authorization: ☐ OFF
   • Standard flow: ☑ ON
   • Direct access grants: ☐ OFF (nicht empfohlen)
6. → Next
7. Valid redirect URIs: die Redirect-URI aus LIVCK eintragen
8. Web origins: leer (nicht benötigt)
9. → Save

3. Client-Secret kopieren

Clients → livck → Credentials → Client secret → Copy

Das Secret ist nur hier sichtbar — sicher ablegen.

4. Gruppen anlegen

Realm livck → Groups → Create group

Lege pro LIVCK-Rolle eine Gruppe an:

5. Benutzer den Gruppen zuweisen

Users → Benutzer auswählen → Groups tab → Join group → Gruppe wählen → Join

Wiederholen für jeden Benutzer / jede Rolle.

6. Groups-Claim im Token aktivieren

Keycloak liefert die Gruppen nicht automatisch im ID-Token. Du brauchst einen Protocol Mapper:

1. Clients → livck → Client scopes tab
2. Scope openid (oder den dedizierten Client-Scope) → Mappers tab → Add mapper → By configuration
3. Vorlage: Group Membership
4. Konfiguration:

5. → Save

7. Zugangsdaten sammeln

• Issuer-URL: https://keycloak.example.com/realms/livck (ohne /.well-known/openid-configuration am Ende — LIVCK hängt das Discovery-Suffix automatisch an)
• Client-ID: aus Schritt 2 (livck)
• Client-Secret: aus Schritt 3

Die Issuer-URL findest du auch unter Realm Settings → General → Issuer.

8. In LIVCK eintragen

Einstellungen → Organisation → SSO → Verbindung bearbeiten → Konfiguration:

→ Konfiguration speichern

9. Domain verifizieren

Siehe SSO einrichten → Domain verifizieren.

10. Mapping anlegen

Einstellungen → Organisation → SSO → Verbindung → Mappings:

Pro Gruppe einen Eintrag:

• IdP-Gruppe: der Pfad aus Schritt 4 (z.B. /livck-admin — führender Schrägstrich und Groß-/Kleinschreibung werden von LIVCK ignoriert)
• Rolle: die entsprechende LIVCK-Rolle

→ Hinzufügen

11. Testen

Klicke auf Login testen. Im Dry-Run-Report sollte stehen:

• Gruppen: ["livck-admin"]
• Ermittelte Rollen: Admin
• Würde sich anmelden: ja

Weg B: Realm-Rollen (alternativ)

Verwende diesen Weg nur, wenn du bereits Keycloak-Rollen pflegst und keine Gruppen anlegen möchtest.

1. Client registrieren

Wie Weg A, Schritte 1–3.

2. Realm-Rollen anlegen

Realm Roles → Create role

3. Benutzer die Rollen zuweisen

Users → Benutzer → Role mapping tab → Assign role → Rolle wählen

4. Realm-Rollen als flachen Claim ausliefern

Keycloak liefert Realm-Rollen verschachtelt in realm_access.roles. Damit LIVCK sie als Groups-Claim auslesen kann, legst du einen Mapper an, der sie flach als eigenen Claim ausgibt:

1. Clients → livck → Client scopes tab → openid → Mappers tab → Add mapper → By configuration
2. Vorlage: User Realm Role
3. Konfiguration:

4. → Save

5. In LIVCK eintragen

6. Mapping anlegen

• IdP-Gruppe: exakt der Rollenname (z.B. livck-admin)
• Rolle: die LIVCK-Rolle

7. Nachteil: verschachtelte Default-Rollen

Ohne den eigenen Mapper (Weg B Schritt 4) bleiben die Rollen in realm_access.roles verschachtelt. LIVCK kann diese Struktur nicht auslesen — der groups-Claim bleibt leer und der Login schlägt fehl.

Lösung: Verwende Weg A (Gruppen) oder den Mapper aus Schritt 4.

Troubleshooting

Im Test-Login steht "kein groups-Claim empfangen"

Im Test-Login stehen Pfade statt reinen Namen

Du hast "Full group path" im Mapper aktiviert. Das ist in Ordnung — LIVCK entfernt den führenden Schrägstrich automatisch, daher matchen /livck-admin und livck-admin gleichermaßen.

Im Test-Login steht die richtige Gruppe, aber Login schlägt fehl

Prüfe:

• Ist die E-Mail-Domain verifiziert? (SSO → Domains)
• Ist die Verbindung aktiviert?
• Hat der Benutzer eine verifizierte E-Mail im Keycloak?
• Stimmt die Redirect-URI exakt? (inkl. HTTPS-Schema, kein Trailing-Slash)

Issuer-URL validieren

Die Issuer-URL muss exakt sein — ohne Trailing-Slash und ohne /.well-known/openid-configuration am Ende. LIVCK hängt das Discovery-Suffix automatisch an.

Richtig:

https://keycloak.example.com/realms/livck

Falsch:

https://keycloak.example.com/realms/livck/.well-known/openid-configuration
https://keycloak.example.com/realms/livck/
https://keycloak.example.com/auth/realms/livck   ← alter Pfad (nur Keycloak < 17)

"Invalid issuer" oder Discovery schlägt fehl

• Prüfe, dass die Realm-URL von außerhalb deines Netzwerks erreichbar ist.
• Keycloak muss mit gügltigem TLS-Zertifikat laufen — LIVCK validiert die Discovery-Dokumente.
• Falls du hinter einem Reverse-Proxy betreibst: stelle sicher, dass Keycloak den proxy-headers Modus kennt (KC_PROXY_HEADERS=true bei Quarkus).

Client-Authentication-Fehler (401)

• Client-Secret korrekt kopiert? (nicht der Client-ID)
• Client authentication ist im Client auf ON?
• Redirect-URI stimmt exakt überein?

Weiterführende Themen

• Enterprise SSO – Übersicht
• Rollen & Berechtigungen – Ziel der Gruppen-Zuordnung
• Mitglieder – Wer gehört zur Organisation
• Entra ID (Azure AD) einrichten – Alternative mit App-Rollen