p2-inc/keycloak-skills / benchmarks/keycloak-password-email-otp-mfa/environment/skills/passwordEmailOtpMfaMcp
passwordEmailOtpMfaMcp
VerifiedHarden existing password login with a one-time code emailed as a SECOND factor, on a Phase Two hosted Keycloak, driven through the Keycloak MCP server. Use this for "2FA by email", "MFA by email", "require a code after the password", or "email-based two-factor". The password stays required and gates the code - a wrong password must never send mail. Not passwordless email OTP (a different flow that removes the password), and not WebAuthn or TOTP as a second factor.
passwordEmailOtpMfaMcp
Step 0 — Is the MCP surface actually here?
Do this before any tool call. Check your tool list once, now, for:
bindClientAuthenticationFlow · bindRealmAuthenticationFlow · setExecutionAuthenticatorConfig · setSmtpSettings · whoAmI
- All present → say "Using the Keycloak MCP tools", then follow this skill as written.
- Any missing → say "Keycloak MCP tools unavailable in this session (missing: …) — using the
Keycloak admin REST API instead", then keep reading. Every stage below still applies: the
behaviour it configures is a property of Keycloak, not of the transport. Only the calls change —
carry out each stage against the admin REST API (
$KC_URL/admin/realms/{realm}/...) with an admin token. If the sibling skillpasswordEmailOtpMfaRestis loaded, use its exact REST recipes.
Decide once, here. Do not call an MCP tool to discover whether it exists, and do not alternate between the two paths afterwards — discovering the gap a step at a time is measurably more expensive than committing up front.
Say which path you took either way: a run that silently swaps tooling is indistinguishable from one that never had the tools.
What this is, and what it isn't
Password stays. A correct password is necessary but not sufficient — after it, the user must
also enter a 6-digit code emailed to their account. Not passwordless: traditional login hardened
with a second factor, using a different first step than admin-email-otp-login-mcp.md's fully
passwordless flow:
admin:email-otp-login (passwordless) | This doc (password + OTP, two-factor) | |
|---|---|---|
| First step | ext-auth-username-auth-note (identifier only) | auth-username-password-form (stock Keycloak — validates the password) |
| Getting the emailed code requires... | Just typing a known email address | Knowing the account's password |
| Security model | Possession of the inbox is the only factor | Password + inbox |
Both use ext-email-otp as the second execution and both need realm SMTP; only the first step
differs, and that's the entire point.
Tools this skill drives (Keycloak MCP server)
| Purpose | Tool |
|---|---|
| Identify caller / realm | whoAmI |
| Confirm no matching flow already exists | listAuthenticationFlows |
| Author the flow and bind it, in one call | importAuthenticationFlow (needs the atomic-flows extension) |
Inspect / adjust the ext-email-otp step's config | listFlowExecutions / setExecutionAuthenticatorConfig |
| Configure outgoing mail | setSmtpSettings |
| Bind an already-existing flow | bindRealmAuthenticationFlow / bindClientAuthenticationFlow |
| Confirm bindings | getAuthenticationBindings |
| Look a user up when testing | findUser |
Prerequisite: the keycloak-magic-link extension
Same as plain email OTP: ext-email-otp comes from
p2-inc keycloak-magic-link, not stock
Keycloak. If unavailable, say so and stop rather than substituting Keycloak's own OTP.
Stage 1 — Establish identity and target realm
whoAmI; confirm the target deployment/realm and which client should get password+OTP.
Stage 2 — Author the flow
Call listAuthenticationFlows first. Then importAuthenticationFlow with the arrays from
../assets/username-password-email-otp-flow.partial-import.json,
plus the binding:
{
"authenticationFlows": [ /* from the asset */ ],
"authenticatorConfig": [ /* from the asset */ ],
"browserFlowBinding": "email-otp-flow"
}
This is the one place auth-username-password-form is the right identifier step — the
opposite of plain email OTP, where the same authenticator would wrongly demand a password in a
flow meant to have none. Here demanding the password is the entire point:
| Execution | Requirement | Why |
|---|---|---|
auth-username-password-form | REQUIRED | The gate. Stock Keycloak; validates the password before anything else runs. |
ext-email-otp | REQUIRED | Only reached after a correct password. Generates the code, mails it, verifies the input. |
Verified live, not just from source — three real logins against a running deployment:
| Attempt | Result |
|---|---|
| Correct password | Reaches the OTP form; a real code is emailed |
| Wrong password | Rejected with "Invalid username or password." — the OTP step is never reached, no mail sent |
| Unknown username | Same generic message as wrong password — no separate signal |
The wrong-password row is what proves this is genuinely two-factor: knowing the email address is worthless without the password, since the code is never sent until the password step succeeds.
The extension hash-prefixes the created alias — read it back from the response rather than
assuming. A 404 means the atomic-flows extension isn't installed; offer it and fall back to
admin-password-email-otp-mfa.md's manual REST sequence only if declined.
Stage 3 — The one config option
Same shared key as plain email OTP: ext-magic-create-nonexistent-user. It matters less here — a
user needs a password to reach this step at all — but leave it at its safe false default
unless there's a specific reason for this flow to create accounts. Use
setExecutionAuthenticatorConfig to change it, finding the execution with listFlowExecutions.
Stage 4 — Realm mail settings
setSmtpSettings. Same silent-failure trap as every magic-link-family flow — verify by checking
what actually left, not by trusting success.
Stage 5 — Bind it
| Surface | Tool |
|---|---|
| Realm-wide | bindRealmAuthenticationFlow(bindingType="browser", flowAlias=...) |
| Single client | bindClientAuthenticationFlow(clientId=..., bindingType="browser", flowAlias=...) |
Skip if already bound in the import payload. Ask which the user wants. Verify with
getAuthenticationBindings, passing clientId for a client-level binding — the realm-level
values alone won't show it.
Stage 6 — Behaviors worth knowing
- The password step's brute-force/lockout behavior is whatever the realm already has configured — this flow doesn't need the separate brute-force decision the fully-passwordless variant does, since the password step already gates guessing before OTP is ever reached.
- This doesn't change password reset/recovery — it only adds a second factor on top of existing password login.
- A fresh test user with no name on file can pick up
VERIFY_PROFILE, interrupting right after a correct code with an unrelated profile screen — not a flow bug. - Everything else about
ext-email-otp(no independent TTL, auth-session-note caching, built-in resend) is identical to the passwordless variant — seeadmin-email-otp-login-mcp.md.
Stage 7 — Verify by logging in, not by reading configuration
- Correct username + correct password → OTP form → real emailed code → authorization code,
stateunchanged. - Correct username + wrong password → rejected immediately, generic message; confirm no mail was sent — proves the password gates the OTP rather than merely preceding it.
- Unknown username → same generic rejection as (2), no separate signal.
Common errors
- OTP email never arrives even after a correct password — realm SMTP unconfigured (Stage 4).
- A wrong password still reaches the OTP form — the flow was authored with the wrong
identifier step (e.g.
ext-auth-username-auth-note, which doesn't check a password at all) instead ofauth-username-password-form. - Unknown users get a different error than wrong-password users — not stock behavior; check nothing custom sits in front of the combined form.
ext-email-otpnot offered — thekeycloak-magic-linkextension isn't installed.- A fresh test user hits an unrelated profile screen after the correct code —
VERIFY_PROFILE, not a flow bug. - A required MCP tool is missing — report it and stop; do not switch to REST unsolicited.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |