p2-inc/keycloak-skills / benchmarks/keycloak-step-up-authentication/environment/skills/stepUpAuthenticationMcp
stepUpAuthenticationMcp
Verifiedstep-up-authentication
Step-up authentication: ACR → LoA, self-locking sessions — via MCP
Same outcome as admin-step-up-authentication.md; read that
file for the flow shape, ACR → LoA mapping, application side, the please-openit PIN variant, the
traps, and verification steps — they aren't duplicated here. This file is the MCP tool mapping onto
that same shape. Also read flow-execution-order.md before authoring:
the two level sub-flows here are CONDITIONAL, and their relative order (level 1 before level 2) is
load-bearing in exactly the way that file warns about.
Tools
| Step | Tool |
|---|---|
| Top-level flow | addFlow |
auth-cookie, identity-provider-redirector | addAuthenticator (ALTERNATIVE, with priority) |
| "Step-up forms" sub-flow | addSubFlow (ALTERNATIVE, with priority) |
| "Levels" sub-flow | addSubFlow (REQUIRED, with priority) |
| "Level 1" / "Level 2" CONDITIONAL sub-flows + their condition | addConditional — builds the CONDITIONAL-sub-flow-plus-condition shape in one call; still pass priority so Level 1 lands before Level 2 |
auth-username-password-form inside Level 1, auth-otp-form inside Level 2 | addAuthenticator (REQUIRED) |
The condition's config (loa-condition-level, loa-max-age) | addAuthenticatorConfig |
| Verify order and shape | listFlowExecutions |
| Repair order | raiseExecutionPriority / lowerExecutionPriority, or reorderFlowExecutions where present |
ACR → LoA map, client minimum.acr.value | None — admin console. No tool sets an arbitrary realm or client attribute (updateOidcClient covers only redirect URIs, web origins and enabled). See "Console handoff" |
| Bind the flow | bindRealmAuthenticationFlow / bindClientAuthenticationFlow |
Tell the developer at the start, before the first tool call, that two settings at the end are
theirs to make in the admin console (below) — a Phase Two hosted deployment has no admin REST
credential, so there is no other route, and discovering that mid-task is the costly way to learn
it. Confirm addConditional, addAuthenticatorConfig, and listFlowExecutions are present before
starting — the component path in references/README.md's "Authoring flows" section is the default
even on MCP, since no single tool authors this whole shape in one call. If the server also exposes
importAuthenticationFlow (the keycloak-atomic-auth-flows extension), a hand-authored
*.partial-import.json of the shape in admin-step-up-authentication.md works the same way the
other intents' assets do and avoids the order-repair step entirely, since the import carries the
asset's own priority values.
Build order
addFlow— the top-level flow.addAuthenticator× 2 —auth-cookie,identity-provider-redirector, both ALTERNATIVE,priority0 and 10.addSubFlow— "Step-up forms", ALTERNATIVE,priority20.addSubFlow— "Levels", REQUIRED, nested inside "Step-up forms".addConditional— "Level 1", nested inside "Levels",priority0, with its condition (conditional-level-of-authentication,loa-condition-level=1,loa-max-age=36000).addAuthenticator—auth-username-password-form, REQUIRED, inside "Level 1".addConditional— "Level 2", nested inside "Levels",priority10 — after Level 1; getting this order backwards demands the OTP step on every first login (see the shared reference file's "traps" for why).addAuthenticator—auth-otp-form, REQUIRED, inside "Level 2".addAuthenticatorConfigon each level's condition execution with its ownloa-condition-level/loa-max-age— the two conditions are separate executions sharing a providerId, so match each one within its own sub-flow, not by providerId alone.listFlowExecutions— verify the whole tree: every level bucket-pure, Level 1 before Level 2. Repair withraiseExecutionPriority/lowerExecutionPriorityif not.bindRealmAuthenticationFlow(orbindClientAuthenticationFlowfor a single client) to the new flow's alias/id.- Hand the developer the console steps below, all in one message.
Console handoff: ACR → LoA map and minimum ACR
Without the map, nothing translates acr_values=gold into level 2, so the flow built above never
steps up. Give the developer these exact locations — and do not report the task done until they
confirm, since nothing here can read either value back:
- Realm settings → General → ACR to LoA Mapping — add
silver→1andgold→2, then Save. (Stored as the realm attributeacr.loa.map.) - Only for a client that must always require level 2 (e.g.
acme-payments): Clients → client → Advanced → Advanced settings → Minimum ACR value =gold, then that section's own Save. This is a client setting, not a realm one. Don't confuse it with Default ACR values in the same section — that is a default the browser can override, so it enforces nothing. A client not pinned this way gets level 2 only when the application requestsacr_values=gold. - Check Realm settings → Tokens → Access Token Lifespan is ≤ 5 minutes (the level-2
loa-max-age); the default already is. A longer lifespan lets a stalegoldtoken outlive the self-locking window.
Leave the ACR to LoA Mapping on the client's Advanced tab empty — one realm-level map is the shared reference file's advice.
Verify with real logins exactly as in the shared reference file's "Verifying this actually works" — config read-back alone doesn't catch an order mistake.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |