p2-inc/keycloak-skills / benchmarks/keycloak-email-otp-login/environment/skills/emailOtpLoginRest
emailOtpLoginRest
VerifiedTurn on passwordless login by a one-time code emailed to the user, on a self-managed Keycloak running the p2-inc keycloak-magic-link extension, using the Admin REST API only (no 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 (none ships auto-created), the load-bearing identifier-step choice that decides whether the realm leaks which addresses have accounts, realm SMTP, and why brute-force protection matters for a 6-digit code. Not Keycloak's TOTP/HOTP authenticator apps, and not magic link (a clicked link rather than a typed code).
emailOtpLoginRest
What this is, and what it isn't
The user types an identifier, receives a 6-digit numeric code by email, and types that code in
to finish logging in. No password, ever. This is the sibling mechanism that
admin-passwordless-magic-link.md explicitly says it does not cover ("a one-time code typed in
— a sibling authenticator, not covered here"):
| Magic link | Email OTP (this doc) | |
|---|---|---|
| What arrives by email | A signed action-token link to click | A 6-digit code to type |
| Authenticator | ext-magic-form | ext-email-otp |
| Built-in flow ships with the provider? | Yes (magic link, auto-created) | No — a flow must be authored |
| Works if the mail client rewrites links | Fragile | Unaffected (nothing to click) |
Both come from the same extension, and both need realm SMTP.
Prerequisite: the keycloak-magic-link extension
ext-email-otp is provided by p2-inc keycloak-magic-link
(the same jar that provides ext-magic-form), not by stock Keycloak. Phase Two's own Keycloak
distribution bundles it. Confirm it's present before anything else:
BASE=http://localhost:8080/auth # include the relative path if one is configured
H="Authorization: Bearer $ADMIN_TOKEN"
REALM=<realm>
curl -s "$BASE/admin/realms/$REALM/authentication/authenticator-providers" -H "$H" \
| jq -r '.[] | select(.id=="ext-email-otp")'
Empty output means the extension isn't installed — say so and stop. There is no stock-Keycloak equivalent (Keycloak's own OTP authenticators are TOTP/HOTP against a registered authenticator app, a different mechanism requiring device enrollment).
Author the flow — no built-in one exists
Unlike magic-link (where the provider auto-creates a magic link flow on every realm), nothing
auto-creates an email-OTP flow. Confirm none exists, then author one.
The shape, from ../assets/email-otp-flow.partial-import.json:
| Sub-flow | Execution | Requirement | Why it's here, and why in this position |
|---|---|---|---|
| top-level | auth-cookie | ALTERNATIVE | An existing SSO session still works. |
| top-level | identity-provider-redirector | ALTERNATIVE | A federated path bypasses the forms sub-flow. |
| top-level | forms sub-flow | ALTERNATIVE | Taken when neither of the above applies. |
| forms | ext-auth-username-auth-note | REQUIRED | Load-bearing, and the choice here matters. ext-email-otp reads the attempted username off the auth session (MagicLink.getAttemptedUsername) rather than collecting an address itself, so an identifier step must run first. Use ext-auth-username-auth-note (p2-inc keycloak-orgs) here, not stock auth-username-form — see the anti-enumeration section below for why this choice is not cosmetic. |
| forms | ext-email-otp | REQUIRED | Generates the code, mails it, renders the code form, and verifies the input. |
Do not put ext-email-otp first, and do not drop the identifier step — that combination
produces a silent no-email outcome rather than an error.
Two authoring paths, and one that does not work:
| Path | Cost | Requires |
|---|---|---|
POST /admin/realms/{realm}/authentication-flow/import?force={bool} — authors the flow and binds it in one call | One call | The p2-inc keycloak-atomic-auth-flows extension |
| Manual sequence: create flow → create sub-flow → add each execution → set requirements → attach config → bind | Many calls | Nothing beyond stock Admin REST |
POST /admin/realms/{realm}/partialImport | — | Does not work. No handler for authentication flows: HTTP 200, added: 0, nothing created, no error. |
Offer the extension when it isn't installed (it 404s clearly). Strip ifResourceExists from the
asset before sending — the atomic payload rejects unknown fields — and read the created alias back
from the response, since the extension hash-prefixes it.
Manual path, if that's the choice:
FLOW='email-otp-flow'
SUB='Email OTP forms'
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}"
# The sub-flow is created AS an execution of the parent.
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(jq -rn --arg f "$FLOW" '$f|@uri')/executions/flow" \
-H "$H" -H 'Content-Type: application/json' \
-d "{\"alias\":\"$SUB\",\"provider\":\"basic-flow\",\"type\":\"basic-flow\"}"
for p in auth-cookie identity-provider-redirector; do
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(jq -rn --arg f "$FLOW" '$f|@uri')/executions/execution" \
-H "$H" -H 'Content-Type: application/json' -d "{\"provider\":\"$p\"}"
done
for p in ext-auth-username-auth-note ext-email-otp; do # order matters, see the table above
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(jq -rn --arg f "$SUB" '$f|@uri')/executions/execution" \
-H "$H" -H 'Content-Type: application/json' -d "{\"provider\":\"$p\"}"
done
# New executions start DISABLED, and the add calls ignore a "requirement" field. Set each
# one with PUT on the flow's executions collection, sending the execution's WHOLE row back
# with only the requirement changed: the PUT also writes "priority", so a body of just
# {id, requirement} resets it to 0 (see flow-execution-order.md). A sub-flow's own row has
# no providerId; it is matched by its alias (displayName).
set_req() { # <flow alias> <providerId or sub-flow alias> <requirement>
F=$(jq -rn --arg f "$1" '$f|@uri')
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" "$SUB" ALTERNATIVE
set_req "$SUB" ext-auth-username-auth-note REQUIRED
set_req "$SUB" ext-email-otp REQUIRED
# Each PUT answers 204.
# Attach the config (next section) to the ext-email-otp execution.
EID=$(curl -s "$BASE/admin/realms/$REALM/authentication/flows/$(jq -rn --arg f "$SUB" '$f|@uri')/executions" -H "$H" \
| jq -r '.[] | select(.providerId == "ext-email-otp") | .id')
curl -s -o /dev/null -w 'config: %{http_code}\n' -X POST "$BASE/admin/realms/$REALM/authentication/executions/$EID/config" \
-H "$H" -H 'Content-Type: application/json' \
-d '{"alias":"email-otp-config","config":{"ext-magic-create-nonexistent-user":"false"}}'
# 201 = attached.
The identifier-step choice: this is where anti-enumeration is actually decided
Verified empirically, not just from source — this is the trap that's easy to get wrong even having read the authenticator code correctly, because the leak comes from a different authenticator entirely:
- Wiring the identifier step as stock
auth-username-formmakes an unregistered address return "Invalid username or email." on the spot, beforeext-email-otpever runs. That's a real enumeration leak — the response genuinely differs for a registered vs. unregistered address — and it happens regardless ofext-email-otp's own force-create setting, because the rejection happens one step earlier. - Wiring it as
ext-auth-username-auth-note(the p2-inckeycloak-orgsauthenticator used for exactly this purpose elsewhere in this router) sets the attempted username without validating existence, and control reachesext-email-otp, whose own null-user handling is anti-enumeration-safe: with force-create off, an unmatched address renders the identical code form with no email sent and no error.
So "an unregistered address gets an identical response" is not automatically true of email
OTP — it depends entirely on which authenticator collects the identifier, and the answer for
the asset in this repo is ext-auth-username-auth-note. If you ever see this flow authored with
auth-username-form instead (including in fixtures that predate this correction), treat the
enumeration leak as real and swap the authenticator rather than assuming the "same as magic-link"
behavior applies.
The one config option — and how it differs from magic-link
ext-email-otp has exactly one configurable property, and it is the same key magic-link
uses (a shared constant in the extension), which is why it looks out of place:
{ "alias": "email-otp-config", "config": { "ext-magic-create-nonexistent-user": "false" } }
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/executions/<ext-email-otp-exec-id>/config" \
-H "$H" -H 'Content-Type: application/json' \
-d '{"alias":"email-otp-config","config":{"ext-magic-create-nonexistent-user":"false"}}'
The default differs from magic-link's, in the safe direction. Verified in the extension's
source: ext-magic-form defaults this to true (which silently provisions an account for any
address typed — the trap admin-passwordless-magic-link.md warns about), whereas
ext-email-otp defaults it to false. So for email OTP you do not have to remember to
turn it off. Setting it explicitly, as the asset does, is documentation rather than a fix — but
do set it to true deliberately if self-registration-by-OTP is actually wanted (note that doing
so also reopens the enumeration question above, since a match will now always exist).
Nothing else is configurable. In particular the code itself is not tunable: it is always a
6-digit numeric string (SecretGenerator.DIGITS), with no length, alphabet, or separate TTL
setting.
Realm mail settings — required, and it fails silently
Same dependency and same trap as magic-link: a realm ships with no SMTP settings at all, and a failed send is swallowed internally. Read-modify-write the realm representation (a PUT that omits fields resets them):
{
"smtpServer": {
"host": "smtp.example.com", "port": "587", "from": "noreply@example.com",
"auth": "true", "user": "...", "password": "...", "starttls": "true", "ssl": "false"
}
}
# Read-modify-write: a PUT that omits fields resets them. With auth "true", add user/password.
curl -s "$BASE/admin/realms/$REALM" -H "$H" \
| jq '.smtpServer = {host: "<smtp-host>", port: "<smtp-port>", from: "<from-address>",
auth: "false", starttls: "false", ssl: "false"}' \
| curl -s -o /dev/null -w 'smtp: %{http_code}\n' -X PUT "$BASE/admin/realms/$REALM" -H "$H" \
-H 'Content-Type: application/json' --data-binary @-
Verify by checking what actually left, not by trusting a 204.
Bind it
# Realm-wide: browserFlow takes the flow's ALIAS.
curl -s -o /dev/null -w 'realm: %{http_code}\n' -X PUT "$BASE/admin/realms/$REALM" -H "$H" \
-H 'Content-Type: application/json' -d "{\"browserFlow\":\"$FLOW\"}"
# Or one client: authenticationFlowBindingOverrides.browser takes the flow's ID, not its alias.
FLOW_ID=$(curl -s "$BASE/admin/realms/$REALM/authentication/flows" -H "$H" \
| jq -r --arg a "$FLOW" '.[] | select(.alias == $a) | .id')
CID=$(curl -s "$BASE/admin/realms/$REALM/clients?clientId=<client-id>" -H "$H" | jq -r '.[0].id')
curl -s "$BASE/admin/realms/$REALM/clients/$CID" -H "$H" \
| jq --arg f "$FLOW_ID" '.authenticationFlowBindingOverrides.browser = $f' \
| curl -s -o /dev/null -w 'client: %{http_code}\n' -X PUT "$BASE/admin/realms/$REALM/clients/$CID" \
-H "$H" -H 'Content-Type: application/json' --data-binary @-
Ask which the user wants — realm-wide affects every client including the admin and account consoles, which usually should keep their own login path.
Behaviors worth knowing before you're asked about them
All verified empirically against a live deployment, not just from source:
- Anti-enumeration depends on the identifier step — see the section above. With
ext-auth-username-auth-note, an unregistered address gets the identical code-form response, no email, no error. It also means "I never got a code" is indistinguishable from "that address has no account" — by design, once the right identifier step is used. - Refreshing the page does not resend. The code lives in an auth-session note
(
user-auth-note-otp-code) and the send is skipped whenever that note is already set. - There is a built-in resend. Posting a
resendform parameter clears the note and issues a fresh code. The bundledotp-form.ftlexposes this. - No independent code expiry. The code has no TTL of its own; it lives as long as the authentication session does. Shorten the realm's login timeouts if you need a tighter window.
- Wrong codes feed brute-force protection. A mismatch is reported as
LOGIN_ERROR/invalid_codeand raised as anINVALID_CREDENTIALSfailure challenge, so the realm's brute-force settings actually govern guessing attempts. Realms ship with brute-force off — a 6-digit code with unlimited attempts is weak, so turn it on when using this flow. - Success marks the email verified. Completing an email-OTP login sets
emailVerified=trueon the user, since possession of the address was just proven. Useful, but be aware it mutates the user. - New users need a name on file. A user created without
firstName/lastNamecan pick up aVERIFY_PROFILErequired action, which interrupts the flow with an unrelated profile-completion screen right after a correct code. Not specific to email OTP, but easy to mistake for a flow bug when testing against a freshly created user.
Verifying this actually works
Configuration alone proves nothing — drive a real login:
- Start an authorization-code request against the bound client. The identifier form appears;
submit a registered address. The code form (
otp-form.ftl) appears, and an email arrives with a 6-digit code. - Submit the emailed code → the browser returns to the app's
redirect_uriwith an authorization code,stateunchanged. - Submit a wrong code → rejected with an invalid-code message, and the attempt counts toward brute force if enabled.
- Repeat step 1 with an unregistered address → the code form still appears (identical
response, assuming
ext-auth-username-auth-noteis the identifier step), but confirm no mail was sent and no user was created.
Troubleshooting
| Symptom | Cause |
|---|---|
| Code form appears but no email ever arrives, for any address | Realm SMTP unconfigured or wrong — the send failure is swallowed |
| Unregistered address gets "Invalid username or email" instead of the code form | The identifier step is stock auth-username-form, which validates existence up front — swap it for ext-auth-username-auth-note |
| No email, and the flow seems to skip straight to the code form with nothing to send to | The identifier step is missing or ordered after ext-email-otp, so there is no attempted username to mail |
| A brand-new account appears for an address nobody registered | ext-magic-create-nonexistent-user was set to "true" |
| Codes accepted indefinitely on repeated guesses | Realm brute-force protection is off (the default) |
ext-email-otp not offered when adding an execution | The keycloak-magic-link extension isn't installed on this Keycloak |
| A refresh doesn't produce a new code | Expected — use the form's resend control; the code is cached in an auth-session note |
| 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 |
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: 471k | 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 |