Tag 11: Flows, Identity Brokering, SAML, Theme
Ziel: Einen eigenen Login-Flow bauen, der OTP nur für Admins verlangt, Benutzer eines Partners per OIDC und SAML anmelden und der Login-Seite ein eigenes Gesicht geben. · Dauer: ca. 120 min · Voraussetzung: Tag 10
Briefing
- Ein Flow ist eine Kette von Schritten (Executions):
Cookie prüfen, Formular, zweiter Faktor. Jeder Schritt ist
REQUIRED,ALTERNATIVE,CONDITIONALoderDISABLED. Eingebaute Flows änderst du nicht, du kopierst sie. - Ein Flow lässt sich pro Client festlegen (Authentication flow overrides). So gilt für notes-web etwas anderes als für die Account-Konsole.
- Identity Brokering: Keycloak lässt einen anderen Identity Provider anmelden und legt beim ersten Mal eine lokale Kopie des Benutzers an. Der andere Provider kann OIDC oder SAML sprechen.
- SAML 2.0 ist der ältere XML-Standard für Single Sign-on, in Unternehmen noch weit verbreitet. Keycloak ist SAML-IdP und SAML-Broker zugleich.
- Ein Theme ändert Aussehen und Texte der Seiten – hier mit ein paar Zeilen CSS und einer Textdatei, ohne eigene Templates.
notes-web ─► Realm lab (Flow browser-notes: OTP nur für notes-admin)
└─ „Partner GmbH" (OIDC) ─► Realm partner (pia)
Account partner ─► „notes Labor (SAML)" ─► Realm lab (anna)
Drill 1: Ein eigener Browser-Flow
source ~/kc-lab/setup/env.sh
mkdir -p ~/kc-lab/tag11
kclogin
uid() { kcadm get users -r lab -q username=$1 -q exact=true --fields id \
--format csv --noquotes; }
kcadm create authentication/flows/browser/copy -r lab -s newName=browser-notes
ex() { kcadm get authentication/flows/browser-notes/executions -r lab; }
ex | jq -r '.[] | [.level, .requirement, .displayName] | @tsv' | tail -8Erwartet:
Logging into http://localhost:8080 as user kcadmin of realm master
Created new copy with id '…'
0 ALTERNATIVE browser-notes forms
1 REQUIRED Username Password Form
1 CONDITIONAL browser-notes Browser - Conditional 2FA
2 REQUIRED Condition - user configured
2 REQUIRED Condition - credential
2 ALTERNATIVE OTP Form
2 DISABLED WebAuthn Authenticator
2 DISABLED Recovery Authentication Code Form
Die Spalte vorne ist die Ebene. Unter forms stehen das Passwortformular und der Unterflow für den zweiten Faktor. Der läuft nur, wenn alle Bedingungen zutreffen: „user configured” heißt, der Benutzer hat schon OTP eingerichtet. Deshalb fragte Keycloak in Tag 10 nur otto nach einem Code. In der Konsole siehst du den Flow unter Authentication → browser-notes.
Fortschritt speichern? Kostenlos registrieren
Drill 2: OTP nur für Admins
Neue Regel für notes: Wer die Rolle notes-admin hat,
braucht immer einen zweiten Faktor – auch wenn er noch keinen
eingerichtet hat. Dafür tauschen wir die beiden Bedingungen gegen „user
role”:
eid() { ex | jq -r --arg n "$1" '[.[] | select(.displayName==$n)] | last | .id'; }
kcadm delete authentication/executions/$(eid "Condition - user configured") -r lab
kcadm delete authentication/executions/$(eid "Condition - credential") -r lab
SUB="browser-notes%20Browser%20-%20Conditional%202FA"
kcadm create authentication/flows/$SUB/executions/execution -r lab \
-s provider=conditional-user-role
RID=$(eid "Condition - user role")
kcadm create authentication/executions/$RID/config -r lab -s alias=nur-notes-admin \
-s 'config.condUserRole=notes-admin'
kcadm create authentication/executions/$RID/raise-priority -r lab
kcadm update authentication/flows/browser-notes/executions -r lab \
-b "{\"id\":\"$RID\",\"requirement\":\"REQUIRED\"}"
kcadm update authentication/flows/browser-notes/executions -r lab \
-b "{\"id\":\"$(eid "OTP Form")\",\"requirement\":\"REQUIRED\"}"
ex | jq -r '.[] | [.level, .requirement, .displayName] | @tsv' | tail -5Erwartet:
Created new execution with id '…'
Created new config with id '…'
1 CONDITIONAL browser-notes Browser - Conditional 2FA
2 REQUIRED Condition - user role
2 REQUIRED OTP Form
2 DISABLED WebAuthn Authenticator
2 DISABLED Recovery Authentication Code Form
eid nimmt mit last den letzten Treffer:
„Condition - user configured” gibt es auch im Unterflow für
Organisationen weiter oben, den lassen wir in Ruhe. Die Konfiguration
nur-notes-admin sagt der Bedingung, welche Rolle sie prüft.
Ist die Rolle da, muss das OTP-Formular durchlaufen werden; fehlt das
Gerät, richtet der Benutzer es zuerst ein. Leerzeichen im Namen des
Unterflows stehen in der URL als %20.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Der Flow gilt für notes
FID=$(kcadm get authentication/flows -r lab \
| jq -r '.[] | select(.alias=="browser-notes") | .id')
NW=$(kcadm get clients -r lab -q clientId=notes-web | jq -r '.[0].id')
kcadm update clients/$NW -r lab -s "authenticationFlowBindingOverrides.browser=$FID"
kcadm get clients/$NW -r lab | jq -c .authenticationFlowBindingOverrides
kcadm create users -r lab -s username=nora -s enabled=true -s [email protected] \
-s emailVerified=true -s firstName=Nora -s lastName=Admin
kcadm set-password -r lab --username nora --new-password lab-user-pw-nora
kcadm add-roles -r lab --uusername nora --rolename notes-admin
echo "$NOTES_URL"Erwartet:
{"browser":"…"}
Created new user with id '…'
http://notes.192.168.64.5.sslip.io:4180
Öffne notes in einem privaten Browserfenster und melde dich als
nora mit lab-user-pw-nora an. Statt notes
kommt die Einrichtung des zweiten Faktors.
Schließ das Fenster, ohne OTP einzurichten. Melde dich in einem neuen
privaten Fenster als anna an: Sie hat
notes-admin nicht und landet direkt in notes. In der
Account-Konsole ($KC_URL/realms/lab/account) braucht auch
nora keinen Code – dort gilt weiter der Flow browser.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ein Partner mit eigenem Realm
Die Partner GmbH hat ihre eigene Benutzerverwaltung. Wir spielen sie mit einem zweiten Realm auf derselben Keycloak-Instanz nach:
P=$KC_URL/realms/partner
kcadm create realms -s realm=partner -s enabled=true -s 'displayName=Partner GmbH'
kcadm create users -r partner -s username=pia -s enabled=true \
-s [email protected] -s emailVerified=true -s firstName=Pia \
-s lastName=Partner
kcadm set-password -r partner --username pia --new-password lab-user-pw-pia
kcadm create clients -r partner -s clientId=lab-broker -s secret=lab-client-secret-123 \
-s "redirectUris=[\"$KC_URL/realms/lab/broker/partner/endpoint\"]"
curl -s $P/.well-known/openid-configuration | jq -r .issuerErwartet:
Created new realm with id 'partner'
Created new user with id '…'
Created new client with id '…'
http://kc.192.168.64.5.sslip.io:8080/realms/partner
Für den Partner ist lab ein ganz normaler OIDC-Client namens
lab-broker. Die Redirect-URI zeigt auf den Broker-Endpunkt
von lab; partner darin ist der Alias, den der Identity
Provider gleich in lab bekommt.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Partner GmbH als Identity Provider
kcadm create identity-provider/instances -r lab -s alias=partner \
-s providerId=keycloak-oidc -s 'displayName=Partner GmbH' -s enabled=true \
-s config.issuer=$P -s config.authorizationUrl=$P/protocol/openid-connect/auth \
-s config.tokenUrl=$P/protocol/openid-connect/token \
-s config.jwksUrl=$P/protocol/openid-connect/certs -s config.useJwksUrl=true \
-s config.validateSignature=true -s config.clientId=lab-broker \
-s config.clientSecret=lab-client-secret-123 \
-s config.clientAuthMethod=client_secret_post \
-s config.pkceEnabled=true -s config.pkceMethod=S256 -s config.syncMode=IMPORT \
-s 'config.defaultScope=openid profile email'
kcadm create identity-provider/instances/partner/mappers -r lab -s name=leser \
-s identityProviderAlias=partner \
-s identityProviderMapper=oidc-hardcoded-role-idp-mapper \
-s config.role=notes-lesen -s config.syncMode=INHERITErwartet:
Created new instance with id 'partner'
Created new mapper with id '…'
Der Mapper leser gibt jedem Benutzer vom Partner die
Rolle notes-lesen. Öffne notes in einem privaten Fenster:
Unter dem Formular steht jetzt Sign in with Partner
GmbH.
Klick darauf, melde dich bei Partner GmbH als pia mit
lab-user-pw-pia an. Statt notes kommt 500 Internal
Server Error. Wer war das?
docker compose -f ~/kc-lab/notes/compose.yaml logs oauth2-proxy --since 5m \
| grep -o 'Error redeeming.*'Erwartet:
Error redeeming code during OAuth2 callback: email in id_token ([email protected]) i…
Keycloak hat pia angelegt, aber ihre E-Mail als nicht bestätigt markiert – es weiß nicht, ob der Partner sie geprüft hat. oauth2-proxy verlangt eine bestätigte Adresse. Wir vertrauen dem Partner (Trust email). Die schon angelegte Kopie von pia löschen wir, damit sie neu entsteht:
kcadm get users -r lab -q username=pia -q exact=true \
| jq -c '.[] | {username, emailVerified}'
kcadm update identity-provider/instances/partner -r lab -s trustEmail=true
kcadm delete users/$(uid pia) -r lab && echo gelöschtErwartet:
{"username":"pia","emailVerified":false}
gelöscht
Melde dich in einem neuen privaten Fenster noch einmal über Partner GmbH als pia an. Jetzt steht oben „Angemeldet als pia (… notes-lesen …)“. In lab:
PID=$(uid pia)
kcadm get users/$PID/federated-identity -r lab \
| jq -c '.[] | {identityProvider, userName}'
kcadm get users/$PID/role-mappings/realm -r lab | jq -r '.[].name' | sort
kcadm get users/$PID -r lab | jq -c '{username, email, emailVerified}'Erwartet:
{"identityProvider":"partner","userName":"pia"}
default-roles-lab
notes-lesen
{"username":"pia","email":"[email protected]","emailVerified":true}
pia hat in lab kein Passwort. Ihre Kopie ist mit dem Konto beim Partner verknüpft (Identity provider links), die Rolle kommt vom Mapper.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Dasselbe mit SAML
Jetzt andersherum: Die Partner GmbH möchte, dass sich Leute aus lab bei ihr anmelden – per SAML. lab ist dann der SAML-IdP, partner der Service Provider (SP). Jeder SAML-Partner veröffentlicht seine Daten als XML-Metadaten:
curl -s $KC_URL/realms/lab/protocol/saml/descriptor \
| grep -o -E 'entityID="[^"]*"|SingleSignOnService Binding="[^"]*"'Erwartet:
entityID="http://kc.192.168.64.5.sslip.io:8080/realms/lab"
SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
In lab bekommt der SP einen SAML-Client. Seine Client-ID ist die Entity ID des SP – bei einem Keycloak-Realm dessen URL:
kcadm create clients -r lab -s clientId=$P -s protocol=saml -s name=partner-saml \
-s "redirectUris=[\"$P/broker/notes-lab/endpoint\"]" \
-s 'attributes."saml.client.signature"=false' \
-s 'attributes."saml_name_id_format"=username' \
-s 'attributes."saml_force_name_id_format"=true'
SID=$(kcadm get clients -r lab -q clientId=$P | jq -r '.[0].id')Erwartet:
Created new client with id '…'
saml.client.signature=false heißt: lab verlangt keine
signierten Anfragen vom SP. Die NameID – der
Benutzername in der Antwort – ist der username. Auf der
Seite von partner liest Keycloak die Metadaten von lab ein und legt
daraus den Identity Provider an:
kcadm create identity-provider/import-config -r partner -s providerId=saml \
-s fromUrl=$KC_URL/realms/lab/protocol/saml/descriptor -o > ~/kc-lab/tag11/saml.json
jq -c '{singleSignOnServiceUrl, validateSignature}' ~/kc-lab/tag11/saml.json
jq --arg sp "$P" '{alias: "notes-lab", providerId: "saml", enabled: true,
displayName: "notes Labor (SAML)", trustEmail: true,
config: (. + {entityId: $sp, principalType: "SUBJECT", syncMode: "IMPORT",
nameIDPolicyFormat: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"})}' \
~/kc-lab/tag11/saml.json > ~/kc-lab/tag11/saml-idp.json
docker compose -f ~/kc-lab/keycloak/compose.yaml cp ~/kc-lab/tag11/saml-idp.json \
keycloak:/tmp/saml-idp.json
kcadm create identity-provider/instances -r partner -f /tmp/saml-idp.jsonErwartet:
{"singleSignOnServiceUrl":"http://kc.192.168.64.5.sslip.io:8080/realms/lab/protocol/sa…
keycloak-keycloak-1 Copied /home/…/saml-idp.json to keycloak-keycloak-1:/tmp/saml-idp…
Created new instance with id 'notes-lab'
validateSignature ist an: partner prüft jede
SAML-Antwort mit dem Schlüssel aus den Metadaten von lab. Eine Assertion
enthält aber nur die NameID. E-Mail und Namen müssen beide Seiten
ausdrücklich übertragen – lab als Attribut, partner per Mapper zurück
ins Benutzerprofil:
for a in email firstName lastName; do
kcadm create clients/$SID/protocol-mappers/models -r lab -s name=$a -s protocol=saml \
-s protocolMapper=saml-user-property-mapper -s "config.\"user.attribute\"=$a" \
-s "config.\"attribute.name\"=$a"
kcadm create identity-provider/instances/notes-lab/mappers -r partner -s name=$a \
-s identityProviderAlias=notes-lab \
-s identityProviderMapper=saml-user-attribute-idp-mapper \
-s "config.\"attribute.name\"=$a" -s "config.\"user.attribute\"=$a" \
-s config.syncMode=INHERIT
done
echo "$P/account"Erwartet:
Created new model with id '…'
Created new mapper with id '…'
…
http://kc.192.168.64.5.sslip.io:8080/realms/partner/account
Öffne die Account-Konsole von partner in einem privaten Fenster und klick auf Sign in with notes Labor (SAML).
Melde dich bei notes Labor als anna an – du landest in
der Account-Konsole von partner, mit Annas Namen. Ohne die Mapper hätte
partner erst nach E-Mail und Namen gefragt.
AP=$(kcadm get users -r partner -q username=anna -q exact=true | jq -r '.[0].id')
kcadm get users/$AP -r partner | jq -c '{username, email, firstName}'
kcadm get users/$AP/federated-identity -r partner \
| jq -c '.[] | {identityProvider, userName}'Erwartet:
{"username":"anna","email":"[email protected]","firstName":"Anna"}
{"identityProvider":"notes-lab","userName":"anna"}
Fortschritt speichern? Kostenlos registrieren
Drill 7: Ein eigenes Theme
Themes liegen in /opt/keycloak/themes. Dein
compose.yaml bindet dafür seit Tag 1 den Ordner
themes ein. Ein Theme erbt von einem anderen und
überschreibt nur, was anders sein soll:
grep themes ~/kc-lab/keycloak/compose.yaml
T=~/kc-lab/keycloak/themes/notes/login
mkdir -p $T/resources/css $T/messages
cat > $T/theme.properties <<'EOF'
parent=keycloak.v2
styles=css/styles.css css/notes.css
EOF
cat > $T/resources/css/notes.css <<'EOF'
:root {
--keycloak-bg-logo-url: none;
--keycloak-card-top-color: #e8590c;
}
.login-pf body { background-color: #1f3b4d; }
EOF
echo 'loginAccountTitle=Bei notes anmelden' > $T/messages/messages_en.properties
find ~/kc-lab/keycloak/themes/notes -type f | sortErwartet:
- ./themes:/opt/keycloak/themes:ro # eigene Themes (ab Tag 11)
/home/…/kc-lab/keycloak/themes/notes/login/messages/messages_en.properties
/home/…/kc-lab/keycloak/themes/notes/login/resources/css/notes.css
/home/…/kc-lab/keycloak/themes/notes/login/theme.properties
parent=keycloak.v2übernimmt das Standard-Theme mit allen Templates.styleslädt zuerst dessen CSS, dann unsere Datei. Sie setzt zwei CSS-Variablen des Standard-Themes neu und färbt den Hintergrund.messages_en.propertiesüberschreibt einen einzigen Text.
Im Produktionsmodus merkt sich Keycloak Theme-Einstellungen, Texte
und Templates im Cache. Ein neues Theme braucht darum einen Neustart;
danach schalten wir es für den Realm ein. Die Login-Seite holen wir mit
curl über den Client notes-cli:
docker compose -f ~/kc-lab/keycloak/compose.yaml restart keycloak
until curl -sf -o /dev/null $KC_URL/realms/lab; do sleep 3; done
kclogin
kcadm update realms/lab -s loginTheme=notes
LOGIN="$KC_URL/realms/lab/protocol/openid-connect/auth?client_id=notes-cli"
LOGIN="$LOGIN&response_type=code&scope=openid&redirect_uri=http://localhost:9999/cb"
curl -s "$LOGIN" | grep -o -E 'Bei notes anmelden|login/notes/css/[a-z]*\.css'Erwartet:
Container keycloak-keycloak-1 Restarting
Container keycloak-keycloak-1 Started
Logging into http://localhost:8080 as user kcadmin of realm master
login/notes/css/styles.css
login/notes/css/notes.css
Bei notes anmelden
Öffne notes in einem privaten Fenster:
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
kcadm get clients/$NW -r lab | jq -r .authenticationFlowBindingOverrides.browser
kcadm get authentication/flows -r lab \
| jq -r '.[] | select(.alias=="browser-notes") | .id'Erwartet: zweimal dieselbe ID – notes-web nutzt browser-notes.
…
…
for r in lab partner; do
kcadm get identity-provider/instances -r $r \
| jq -r '.[] | [.alias, .providerId] | @tsv'
doneErwartet: ein OIDC-Broker in lab, ein SAML-Broker in partner.
partner keycloak-oidc
notes-lab saml
kcadm get realms/lab --fields loginThemeErwartet:
{
"loginTheme" : "notes"
}
Challenge
Die Überschrift soll „Anmelden bei notes” lauten. Ändere das Theme
und zeig mit curl, dass Keycloak den neuen Text
ausliefert.
Hinweis: Der Text steht in
messages_en.properties. Denk an den Cache.
Lösung
M=~/kc-lab/keycloak/themes/notes/login/messages/messages_en.properties
echo 'loginAccountTitle=Anmelden bei notes' > $M
curl -s "$LOGIN" | grep -o -E 'Bei notes anmelden|Anmelden bei notes'
docker compose -f ~/kc-lab/keycloak/compose.yaml restart keycloak
until curl -sf -o /dev/null $KC_URL/realms/lab; do sleep 3; done
curl -s "$LOGIN" | grep -o -E 'Bei notes anmelden|Anmelden bei notes'Erwartet:
Bei notes anmelden
Container keycloak-keycloak-1 Restarting
Container keycloak-keycloak-1 Started
Anmelden bei notes
Vor dem Neustart kommt der alte Text aus dem Cache. CSS-Dateien liest
Keycloak dagegen bei jedem Abruf neu – dafür hält sie der Browser 30
Tage vor (Cache-Control: max-age=2592000), also im Browser
hart neu laden. Beim Entwickeln eines Themes schaltet man die Caches ab:
--spi-theme--cache-themes=false und
--spi-theme--cache-templates=false – nie in Produktion.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Flows versionieren: Kopierte Flows gehören in den Realm-Export oder nach Terraform (Tag 13). Von Hand in der Konsole gebaute Flows sind schwer zu reproduzieren.
- Step-up: Mit Bedingungen wie „level of
authentication” verlangt Keycloak einen zweiten Faktor erst, wenn eine
Anwendung ihn per
acr_valuesanfordert. - Brokering in der Praxis: Für Azure AD/Entra ID, Google oder GitHub gibt es fertige Provider. Mit Organizations ordnet Keycloak Benutzer anhand der E-Mail-Domain dem richtigen IdP zu.
- SAML: In Produktion signieren beide Seiten, Assertions werden oft zusätzlich verschlüsselt. Zertifikate laufen ab – Metadaten regelmäßig neu einlesen.
- Themes paketieren: Statt eines Ordners ein JAR in
/opt/keycloak/providers. Für aufwendige Login-Seiten gibt es Keycloakify (React).