Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-step-up-authentication/environment/skills/stepUpAuthenticationRest

stepUpAuthenticationRest

Verified

step-up-authentication

Step-up authentication: ACR → LoA, self-locking sessions — via raw Admin REST

What this is, and what it isn't

One Keycloak session, two trust levels that expire separately:

LevelACRAuthenticatorsLasts
1silverauth-username-password-formthe whole SSO session (10 h)
2goldpassword (already satisfied) + auth-otp-form5 minutes, then drops back to silver without logging the user out

This is not admin:password-email-otp-mfa or admin:totp-second-factor: those make every login two-factor, with no levels, and nothing ever expires back to a weaker state. Here, ordinary use never sees the second factor; only a request that explicitly asks for gold does, and a user who already holds silver is asked for only the code — the password step is satisfied already and is never repeated. Dropping from gold back to silver after 5 minutes is the Janua article's "self-locking session": the session locks itself back down without any logout.

See flow-execution-order.md before authoring — this flow's two levels are CONDITIONAL sub-flows, and order inside the level sub-flow is load-bearing: level 1 must be first, or the engine demands level 2 on every first login regardless of what was asked for.

The authenticator: conditional-level-of-authentication

Stock Keycloak (no extension), provider id conditional-level-of-authentication, display name "Condition - Level Of Authentication". Config keys:

  • loa-condition-level — the level (an integer: 1, 2, …) this condition tests for.
  • loa-max-age — seconds; if the current session's ACR was established within this many seconds, the condition is already satisfied and the level's own steps are skipped. Default 36000 (10h). 0 means "always re-prompt" (a payments-style confirmation every time).
BASE=http://localhost:8080/auth
ADMIN_TOKEN=$(curl -s -X POST "$BASE/realms/master/protocol/openid-connect/token" \
  -d client_id=admin-cli -d grant_type=password \
  -d username=<admin-user> -d password=<admin-password> \
  | jq -r .access_token)
H="Authorization: Bearer $ADMIN_TOKEN"
REALM=<realm>

curl -s "$BASE/admin/realms/$REALM/authentication/authenticator-providers" -H "$H" \
  | jq -r '.[] | select(.id=="conditional-level-of-authentication")'

The flow shape

<top-level flow>                              ALTERNATIVE level
├── auth-cookie                                 ALTERNATIVE
├── identity-provider-redirector                 ALTERNATIVE
└── Step-up forms                                ALTERNATIVE   ← sub-flow
    └── Levels                                    REQUIRED      ← sub-flow holding the levels
        ├── Level 1                                CONDITIONAL  ← sub-flow, FIRST
        │   ├── conditional-level-of-authentication  REQUIRED (loa-condition-level=1, loa-max-age=36000)
        │   └── auth-username-password-form           REQUIRED
        └── Level 2                                CONDITIONAL  ← sub-flow, SECOND
            ├── conditional-level-of-authentication  REQUIRED (loa-condition-level=2, loa-max-age=300)
            └── auth-otp-form                          REQUIRED

Level 1 must come before Level 2 in the "Levels" sub-flow. conditional-level-of-authentication answers "has the session already reached at least this level, recently enough" — on a brand-new session nothing has been reached yet, so the first level sub-flow in the list always runs. If Level 2 is listed first, a plain first login (no acr requested at all) is asked for the OTP code before any password exists for it to follow — demanding level 2 on every first login, the opposite of what step-up means. Keeping Level 1 first and Level 2 second means a plain login only ever climbs as high as what's actually requested, one level at a time.

Each level's own sub-flow is CONDITIONAL (occupies the required bucket, per flow-execution-order.md) and must contain its condition plus that level's authenticators, all REQUIRED — a flat ALTERNATIVE/REQUIRED mix at any of these levels silently erases siblings.

Author it (manual sequence — stock Keycloak, no extension)

FLOW='step-up-flow'
FORMS='Step-up forms'
LEVELS='Levels'
LVL1='Level 1'
LVL2='Level 2'

curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows" -H "$H" \
  -H 'Content-Type: application/json' \
  -d "{\"alias\":\"$FLOW\",\"providerId\":\"basic-flow\",\"topLevel\":true,\"builtIn\":false}"

enc() { jq -rn --arg f "$1" '$f|@uri'; }

# Top level: auth-cookie, identity-provider-redirector, then the forms sub-flow.
i=0
for p in auth-cookie identity-provider-redirector; do
  curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$FLOW")/executions/execution" \
    -H "$H" -H 'Content-Type: application/json' -d "{\"provider\":\"$p\",\"priority\":$((i*10))}"
  i=$((i+1))
done
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$FLOW")/executions/flow" \
  -H "$H" -H 'Content-Type: application/json' \
  -d "{\"alias\":\"$FORMS\",\"provider\":\"basic-flow\",\"type\":\"basic-flow\",\"priority\":20}"

# Forms sub-flow: one REQUIRED child, the Levels sub-flow.
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$FORMS")/executions/flow" \
  -H "$H" -H 'Content-Type: application/json' \
  -d "{\"alias\":\"$LEVELS\",\"provider\":\"basic-flow\",\"type\":\"basic-flow\",\"priority\":0}"

# Levels sub-flow: Level 1 THEN Level 2 — order is load-bearing, see above.
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$LEVELS")/executions/flow" \
  -H "$H" -H 'Content-Type: application/json' \
  -d "{\"alias\":\"$LVL1\",\"provider\":\"basic-flow\",\"type\":\"basic-flow\",\"priority\":0}"
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$LEVELS")/executions/flow" \
  -H "$H" -H 'Content-Type: application/json' \
  -d "{\"alias\":\"$LVL2\",\"provider\":\"basic-flow\",\"type\":\"basic-flow\",\"priority\":10}"

# Level 1: condition (level=1, max-age=36000), then the password form.
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$LVL1")/executions/execution" \
  -H "$H" -H 'Content-Type: application/json' \
  -d '{"provider":"conditional-level-of-authentication","priority":0}'
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$LVL1")/executions/execution" \
  -H "$H" -H 'Content-Type: application/json' \
  -d '{"provider":"auth-username-password-form","priority":10}'

# Level 2: condition (level=2, max-age=300), then the OTP form.
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$LVL2")/executions/execution" \
  -H "$H" -H 'Content-Type: application/json' \
  -d '{"provider":"conditional-level-of-authentication","priority":0}'
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$LVL2")/executions/execution" \
  -H "$H" -H 'Content-Type: application/json' \
  -d '{"provider":"auth-otp-form","priority":10}'

# New executions start DISABLED and the add calls ignore "requirement". Set each with
# the execution's whole row (PUT also writes priority — send it back, see
# flow-execution-order.md).
set_req() {  # <flow alias> <providerId or sub-flow alias> <requirement>
  F=$(enc "$1")
  curl -s "$BASE/admin/realms/$REALM/authentication/flows/$F/executions" -H "$H" \
    | jq -c --arg k "$2" --arg r "$3" '.[] | select((.providerId // .displayName) == $k) | .requirement = $r' \
    | curl -s -o /dev/null -w "$2 -> $3: %{http_code}\n" -X PUT \
        "$BASE/admin/realms/$REALM/authentication/flows/$F/executions" -H "$H" \
        -H 'Content-Type: application/json' --data-binary @-
}
set_req "$FLOW" auth-cookie ALTERNATIVE
set_req "$FLOW" identity-provider-redirector ALTERNATIVE
set_req "$FLOW" "$FORMS" ALTERNATIVE
set_req "$FORMS" "$LEVELS" REQUIRED
set_req "$LEVELS" "$LVL1" CONDITIONAL
set_req "$LEVELS" "$LVL2" CONDITIONAL
set_req "$LVL1" conditional-level-of-authentication REQUIRED
set_req "$LVL1" auth-username-password-form REQUIRED
set_req "$LVL2" conditional-level-of-authentication REQUIRED
set_req "$LVL2" auth-otp-form REQUIRED

# Attach the per-level config to EACH condition execution — the two conditions are
# different executions even though they share a providerId, so match within each sub-flow.
attach_loa_config() {  # <sub-flow alias> <level> <max-age> <config-alias>
  EID=$(curl -s "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$1")/executions" -H "$H" \
    | jq -r '.[] | select(.providerId == "conditional-level-of-authentication") | .id')
  curl -s -o /dev/null -w "$4: %{http_code}\n" -X POST \
    "$BASE/admin/realms/$REALM/authentication/executions/$EID/config" -H "$H" \
    -H 'Content-Type: application/json' \
    -d "{\"alias\":\"$4\",\"config\":{\"loa-condition-level\":\"$2\",\"loa-max-age\":\"$3\"}}"
}
attach_loa_config "$LVL1" 1 36000 loa-level-1
attach_loa_config "$LVL2" 2 300 loa-level-2

Read the whole tree back and check every level is bucket-pure and in order before moving on:

curl -s "$BASE/admin/realms/$REALM/authentication/flows/$(enc "$FLOW")/executions" -H "$H" \
  | jq -r '.[] | "\(.index) lvl=\(.level) pri=\(.priority) \(.requirement) \(.providerId // .displayName)"'

ACR → LoA mapping

Realm attribute acr.loa.map, a JSON object as a string inside attributes:

curl -s "$BASE/admin/realms/$REALM" -H "$H" \
  | jq '.attributes["acr.loa.map"] = "{\"silver\":1,\"gold\":2}"' \
  | curl -s -o /dev/null -w 'acr.loa.map: %{http_code}\n' -X PUT "$BASE/admin/realms/$REALM" -H "$H" \
      -H 'Content-Type: application/json' --data-binary @-

The realm's default acr client scope must carry the acr loa level mapper (provider id oidc-acr-mapper) for the acr claim to appear in tokens at all — check it's present on acr under client-scopes, since a realm created before this mapper existed may be missing it.

A client can override the map with the same attribute on the client, but the guide's own advice is to keep it on the realm — one map, used by every client, is easier to keep straight than per-client divergence.

Pin a client to always require gold

Client attribute minimum.acr.value is enforced by Keycloak — unlike default.acr.values (below), a client with this set gets the level even when the request asks for nothing at all:

CID=$(curl -s "$BASE/admin/realms/$REALM/clients?clientId=acme-payments" -H "$H" | jq -r '.[0].id')
curl -s "$BASE/admin/realms/$REALM/clients/$CID" -H "$H" \
  | jq '.attributes["minimum.acr.value"] = "gold"' \
  | curl -s -o /dev/null -w 'minimum.acr.value: %{http_code}\n' -X PUT \
      "$BASE/admin/realms/$REALM/clients/$CID" -H "$H" \
      -H 'Content-Type: application/json' --data-binary @-

default.acr.values (also a client attribute) is only a default sent when the request names none — the user can override it in the browser, so it enforces nothing. minimum.acr.value is what actually gates the client.

Asking for a level, from the application

Not covered by this file beyond quoting the shape — the application side is securing-apps' territory, but the shapes are:

# essential: Keycloak returns one of the listed values or fails outright
?claims={"id_token":{"acr":{"essential":true,"values":["gold"]}}}

# non-essential: a softer hint, Keycloak may ignore it
&acr_values=gold

The resulting ID token carries the level actually reached in its acr claim (silver, gold, or 0 if nothing was ever established — see traps below).

Level 2 variant: a PIN instead of a TOTP code

The Janua self-locking-session article uses a PIN from the third-party please-openit PIN Code Authenticator as Level 2's authenticator instead of stock auth-otp-form. The flow shape is identical — only the authenticator inside Level 2's CONDITIONAL sub-flow changes (its provider id, in place of auth-otp-form). Mention it as an option when a PIN fits the product better than a TOTP code; this file documents the stock auth-otp-form path and doesn't depend on that extension being installed.

Traps

  1. Level 1 must be first in the "Levels" sub-flow. See "The flow shape" above — getting this backwards demands level 2 on every first login.
  2. acr_values/default.acr.values are rewritable by the browser; minimum.acr.value and the application's own check of the acr claim are what actually enforce a level.
  3. Expiry is lazy, not a timer. A level is only re-checked on the next authentication request that reaches this flow; a token already issued at gold stays valid until it expires on its own. Keep the access-token lifespan ≤ the level-2 loa-max-age (300s) or a stale token outlives the self-lock.
  4. loa-max-age: 0 means "this authentication only" — every request for that level re-prompts, useful for a payment-confirmation step rather than a 5-minute window.
  5. A user with no level requested, whose session's level has expired, still gets into SSO — acr comes back 0 (cookie-only, no level reached this request). Applications must handle 0 as "nothing was established", not as an error.
  6. An essential acr that is unmapped or above every configured level is an authentication error, not a silent downgrade to the nearest level.
  7. Levels are cumulative. Level 2 includes level 1's requirements; it is not an alternate method. A different method per ACR (not "more of the same") is a client policy ("ACR to flow"), out of scope here.

Verifying this actually works

  1. No acr requested → only the password form → ID token acr is silver.
  2. Same browser session, now request gold (essential) → only the OTP code form (no password form again) → correct code → ID token acr is gold.
  3. Request gold again immediately → no prompt at all (within loa-max-age) → acr stays gold.
  4. A fresh browser session requesting gold from the start → password, then code → gold.
  5. A wrong code at the level-2 step → rejected, no authorization code issued.
  6. The client pinned with minimum.acr.value=gold → the code is demanded even with no acr requested at all.
  7. An essential acr above every mapped level, or unmapped entirely → an authentication error.
  8. Configuration check: realm acr.loa.map has silver→1, gold→2; access-token lifespan ≤ 300s; level 2's loa-max-age is 300.

Troubleshooting

SymptomCause
Level 2 is demanded on a plain first login with no acr requestedLevel 2's sub-flow is listed before Level 1's inside "Levels"
gold never downgrades back to silver after 5 minutesAccess-token lifespan is longer than loa-max-age; the stale token is still valid
acr claim missing from the token entirelyThe realm's default acr client scope is missing the oidc-acr-mapper ("acr loa level") mapper
acme-payments lets a login through at silverminimum.acr.value not set, or set via default.acr.values instead (a default, not an enforcement)
An unmapped essential acr value logs the user in anyway at some levelNot expected Keycloak behavior — check nothing custom is downgrading instead of erroring
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall