Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-email-otp-login/environment/skills/emailOtpLoginMcp

emailOtpLoginMcp

Verified

Turn on passwordless login by a one-time code emailed to the user, on a Phase Two hosted Keycloak, driven through the Keycloak MCP server. Use this for "email OTP", "email a one-time code", "6-digit login code by email", or "passwordless login with a code instead of a link". Covers authoring the flow with importAuthenticationFlow (none ships auto-created), the load-bearing identifier-step choice that decides whether the realm leaks which addresses have accounts, setSmtpSettings, and setBruteForceProtection. Not Keycloak's TOTP/HOTP authenticator apps, and not magic link.

emailOtpLoginMcp

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 skill emailOtpLoginRest is 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

The user types an identifier, receives a 6-digit numeric code by email, and types it in to finish logging in. No password, ever. This is the sibling mechanism admin-passwordless-magic-link-mcp.md explicitly excludes ("a one-time code typed in — a sibling authenticator, not covered here"):

Magic linkEmail OTP (this doc)
What arrivesA signed action-token link to clickA 6-digit code to type
Authenticatorext-magic-formext-email-otp
Built-in flow ships with the provider?Yes (magic link, auto-created)No — must be authored

Both come from the same keycloak-magic-link extension and both need realm SMTP.

Tools this skill drives (Keycloak MCP server)

PurposeTool
Identify caller / realmwhoAmI
Confirm no email-OTP flow already existslistAuthenticationFlows
Author the flow and bind it, in one callimportAuthenticationFlow (needs the atomic-flows extension)
Inspect / adjust the ext-email-otp step's configlistFlowExecutions / setExecutionAuthenticatorConfig
Configure outgoing mailsetSmtpSettings
Turn on brute-force protection (see Stage 5 — it matters here)setBruteForceProtection
Bind an already-existing flowbindRealmAuthenticationFlow / bindClientAuthenticationFlow
Confirm bindingsgetAuthenticationBindings
Look a user up when testingfindUser

Prerequisite: the keycloak-magic-link extension

ext-email-otp comes from p2-inc keycloak-magic-link — the same jar that provides ext-magic-form — not from stock Keycloak. Phase Two's own distribution bundles it. Keycloak's built-in OTP authenticators are TOTP/HOTP against an authenticator app, which is a different mechanism requiring device enrollment; there is no stock equivalent to email OTP. If the authenticator isn't available on the target, say so and stop rather than substituting TOTP.

Stage 1 — Establish identity and target realm

Call whoAmI; tell the user who they are and which realm the token came from. Confirm the target deployment/realm and which client should use email OTP.

Stage 2 — Author the flow (no built-in one exists)

Call listAuthenticationFlows first. Unlike magic-link — where the provider auto-creates a magic link flow on every realm — nothing auto-creates an email-OTP flow, so expect to author one.

Call importAuthenticationFlow with the arrays from ../assets/email-otp-flow.partial-import.json, plus the binding in the same payload:

{
  "authenticationFlows": [ /* from the asset */ ],
  "authenticatorConfig": [ /* from the asset */ ],
  "browserFlowBinding": "email-otp-flow"
}

For one client instead of realm-wide, use clientFlowBinding: {clientId, browserFlowBinding}. The extension hash-prefixes the alias it creates, so read the real one back from the response rather than assuming. A 404 means the atomic-flows extension isn't installed — offer it, and fall back to admin-email-otp-login.md's manual REST sequence only if the user declines.

The execution order inside the forms sub-flow is load-bearing, and so is WHICH authenticator collects the identifier — verify both if authoring by hand rather than from the asset:

ExecutionRequirementWhy this authenticator, and why this position
ext-auth-username-auth-noteREQUIREDext-email-otp reads the attempted username off the auth session rather than collecting an address itself, so an identifier step must run first. Use this authenticator specifically (p2-inc keycloak-orgs), not stock auth-username-form — see Stage 3's anti-enumeration note for why the choice is load-bearing, not cosmetic.
ext-email-otpREQUIREDGenerates the code, mails it, renders the code form, verifies the input.

Putting ext-email-otp first, or omitting the identifier step entirely, yields a silent no-email outcome rather than an error.

Stage 3 — The identifier-step choice decides anti-enumeration, and the one config option

Verified empirically, not just from source — this is the trap that survives even a correct reading of the authenticator code, because the leak comes from a different authenticator entirely:

  • Identifier step = stock auth-username-form → an unregistered address gets "Invalid username or email." on the spot, before ext-email-otp ever runs. Real enumeration, regardless of ext-email-otp's own config.
  • Identifier step = ext-auth-username-auth-note (Stage 2's choice) → an unregistered address reaches ext-email-otp, whose null-user handling is anti-enumeration-safe with force-create off: identical code-form response, no email, no error.

So "unregistered address gets an identical response" only holds for the specific authenticator combination this asset uses — don't assume it for any email-OTP flow you didn't author this way.

ext-email-otp has exactly one configurable property beyond the identifier-step choice above, and it is the same key magic-link uses (a shared constant in the extension), which is why it reads oddly here: ext-magic-create-nonexistent-user.

Its default differs from magic-link's, in the safe direction. Verified in the extension's source: ext-magic-form defaults it to true (silently provisioning an account for any address typed — the trap the magic-link references warn about), while ext-email-otp defaults it to false. So there is nothing to remember to turn off here; the asset sets it explicitly as documentation. Set it to "true" only if self-registration by OTP is genuinely wanted (and note that also reopens the enumeration question, since a match will now always exist).

To change it later, use setExecutionAuthenticatorConfig on the ext-email-otp execution — find it with listFlowExecutions first.

Nothing else is tunable. The code is always a 6-digit numeric string, with no configurable length, alphabet, or separate TTL.

Stage 4 — Realm mail settings

setSmtpSettings. Same silent-failure trap as magic-link: a realm ships with no SMTP settings and a failed send is swallowed internally, so an unconfigured realm looks identical to a working one from the caller's side. Verify by checking what actually left (a capture point in test contexts), not by trusting a success response.

Stage 5 — Turn on brute-force protection (specific to this mechanism)

A wrong code is raised as an INVALID_CREDENTIALS failure challenge, so the realm's brute-force settings are what actually govern guessing. Realms ship with brute-force off, and a 6-digit code with unlimited attempts is weak — call setBruteForceProtection when standing this up, and ask whether lockout should be temporary (auto-recovering) or permanent.

Stage 6 — Bind it

SurfaceTool
Realm-widebindRealmAuthenticationFlow(bindingType="browser", flowAlias=...)
Single clientbindClientAuthenticationFlow(clientId=..., bindingType="browser", flowAlias=...)

Skip this if you already bound in the import payload. Ask which the user wants — realm-wide affects every client including the admin and account consoles. Verify with getAuthenticationBindings, passing the clientId when the binding was client-level (a client override does not change the realm's browserFlow, so the realm-level values alone will still show the untouched default).

Stage 7 — Behaviors worth knowing before you're asked

Verified empirically against a live deployment, not just from source:

  • Anti-enumeration depends on Stage 2's identifier-step choice. With ext-auth-username-auth-note, an unregistered address gets the identical code-form response — no email, no error, and "I never got a code" becomes indistinguishable from "that address has no account," by design.
  • New users need a name on file. A user with no firstName/lastName can pick up a VERIFY_PROFILE required action, interrupting the flow right after a correct code with an unrelated profile screen. Not specific to email OTP, but easy to mistake for a flow bug while testing.
  • Refreshing does not resend. The code lives in an auth-session note and the send is skipped whenever that note is set.
  • There is a built-in resend (a resend form parameter clears the note and issues a fresh code); the bundled otp-form.ftl exposes it.
  • No independent expiry. The code has no TTL of its own — it lives as long as the authentication session. Shorten the realm's login timeouts for a tighter window.
  • Success marks the email verified (emailVerified=true), since possession was just proven. Useful, but it does mutate the user.

Stage 8 — Verify by logging in, not by reading configuration

  1. A registered address: identifier form → code form → the emailed 6-digit code completes login with an authorization code and the original state.
  2. A wrong code: rejected with an invalid-code message (and counted toward brute force).
  3. An unregistered address: the code form still appears (given ext-auth-username-auth-note as the identifier step), but confirm no mail was sent and no user was created.

Common errors

  • Code form appears, no email ever arrives — realm SMTP unconfigured or wrong (Stage 4); the failure is swallowed.
  • Unregistered address gets "Invalid username or email" instead of the code form — the identifier step is stock auth-username-form; swap it for ext-auth-username-auth-note.
  • Nothing to send to — the identifier step is missing or ordered after ext-email-otp (Stage 2).
  • Unexpected new accounts — ext-magic-create-nonexistent-user was set to "true".
  • A fresh test user hits an unrelated profile-completion screen right after the correct code — VERIFY_PROFILE required action from a missing name on the user, not a flow bug.
  • Codes guessable indefinitely — brute-force protection still off (Stage 5).
  • ext-email-otp unavailable — the keycloak-magic-link extension isn't installed; report it rather than substituting Keycloak's TOTP.
  • A required MCP tool is missing — report it and stop; do not switch to REST unsolicited.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall