Zum Inhalt springen
Trainingslager IT-Trainingslager

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, CONDITIONAL oder DISABLED. 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 -8

Erwartet:

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 -5

Erwartet:

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.

nora hat notes-admin und muss OTP einrichten

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 .issuer

Erwartet:

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=INHERIT

Erwartet:

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.

Login-Seite von lab mit Partner-Knopf

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öscht

Erwartet:

{"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.json

Erwartet:

{"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).

Login-Seite von partner mit SAML-Knopf

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 | sort

Erwartet:

      - ./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.
  • styles lä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:

Die Login-Seite im Theme notes

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'
done

Erwartet: ein OIDC-Broker in lab, ein SAML-Broker in partner.

partner keycloak-oidc
notes-lab   saml
kcadm get realms/lab --fields loginTheme

Erwartet:

{
  "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_values anfordert.
  • 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).