Skip to content

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

emailOtpLoginRest

Verified

Turn 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 linkEmail OTP (this doc)
What arrives by emailA 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 — a flow must be authored
Works if the mail client rewrites linksFragileUnaffected (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-flowExecutionRequirementWhy it's here, and why in this position
top-levelauth-cookieALTERNATIVEAn existing SSO session still works.
top-levelidentity-provider-redirectorALTERNATIVEA federated path bypasses the forms sub-flow.
top-levelforms sub-flowALTERNATIVETaken when neither of the above applies.
formsext-auth-username-auth-noteREQUIREDLoad-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.
formsext-email-otpREQUIREDGenerates 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:

PathCostRequires
POST /admin/realms/{realm}/authentication-flow/import?force={bool} — authors the flow and binds it in one callOne callThe p2-inc keycloak-atomic-auth-flows extension
Manual sequence: create flow → create sub-flow → add each execution → set requirements → attach config → bindMany callsNothing 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-form makes an unregistered address return "Invalid username or email." on the spot, before ext-email-otp ever runs. That's a real enumeration leak — the response genuinely differs for a registered vs. unregistered address — and it happens regardless of ext-email-otp's own force-create setting, because the rejection happens one step earlier.
  • Wiring it as ext-auth-username-auth-note (the p2-inc keycloak-orgs authenticator used for exactly this purpose elsewhere in this router) sets the attempted username without validating existence, and control reaches ext-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 resend form parameter clears the note and issues a fresh code. The bundled otp-form.ftl exposes 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_code and raised as an INVALID_CREDENTIALS failure 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=true on 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/lastName can pick up a VERIFY_PROFILE required 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:

  1. 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.
  2. Submit the emailed code → the browser returns to the app's redirect_uri with an authorization code, state unchanged.
  3. Submit a wrong code → rejected with an invalid-code message, and the attempt counts toward brute force if enabled.
  4. Repeat step 1 with an unregistered address → the code form still appears (identical response, assuming ext-auth-username-auth-note is the identifier step), but confirm no mail was sent and no user was created.

Troubleshooting

SymptomCause
Code form appears but no email ever arrives, for any addressRealm SMTP unconfigured or wrong — the send failure is swallowed
Unregistered address gets "Invalid username or email" instead of the code formThe 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 toThe 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 registeredext-magic-create-nonexistent-user was set to "true"
Codes accepted indefinitely on repeated guessesRealm brute-force protection is off (the default)
ext-email-otp not offered when adding an executionThe keycloak-magic-link extension isn't installed on this Keycloak
A refresh doesn't produce a new codeExpected — 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 codeVERIFY_PROFILE required action from a missing name on the user — not a flow bug
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: 471kUpdated 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