Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-password-or-passkey-login/environment/skills/passwordOrPasskeyLoginMcp

passwordOrPasskeyLoginMcp

Verified

Configure username/password OR a passkey as alternative first-factor methods on one Keycloak login page, via the Keycloak MCP server's tools. Use whenever someone wants "username and password with a passkeys option", "password or passkey", "keep passwords but add passkeys", or a login where either method alone signs the user in. Covers authoring and binding the flow with auth-username-password-form and webauthn-authenticator-passwordless as ALTERNATIVE siblings (and why a REQUIRED or conditional passkey step silently makes it 2FA), the realm's WebAuthn PASSWORDLESS policy block, enrolling an existing user's first passkey, and verifying both paths end to end. Not zero-password login (no password anywhere) and not WebAuthn as a second factor.

Username/password OR passkey login — alternative first-factor methods via MCP

What this is

One browser flow offering two alternative first-factor authentication methods side by side: traditional username and password for users who prefer it or haven't set up a passkey yet, and passkey (WebAuthn passwordless) for users who want passwordless authentication. The user chooses either path at login time through Keycloak's "Try another way" mechanism.

This is neither admin:passwordless-passkey (password removed entirely) nor admin:zero-password-login (magic link replaces password). Here the password remains a valid, fully supported path — the passkey is an additional option, not a replacement. This is the "password with passkey option" pattern: keep existing password infrastructure while offering passkey as a modern alternative.

Say the trade-off: supporting both methods means the account security is bounded by the weakest credential type registered. A user with both a password and a passkey can log in via either. Accounts with only a password remain subject to password risks; accounts with a passkey gain phishing resistance but only if the user actually uses it.

Tools this skill drives (Keycloak MCP server)

PurposeTool
Identify caller / realmwhoAmI
Author the flow (and optionally bind it)importAuthenticationFlow
Read back execution orderlistFlowExecutions
Passkey policygetWebAuthnPasswordlessPolicy / setWebAuthnPasswordlessPolicy
Optional: pre-seed a passkey for a userfindUser → sendRequiredActionEmail
Bind the flowbindRealmAuthenticationFlow / bindClientAuthenticationFlow
Confirm bindingsgetAuthenticationBindings

Capture deploymentId and deploymentRealm and reuse them on every call.

Drive this through the MCP tools. If a required tool is unavailable in this deployment, say so and stop. Do not silently substitute Admin REST calls.

Step 1 — Author the flow

importAuthenticationFlow is the one-shot path when the p2-inc keycloak-atomic-auth-flows extension is present. The flow shape to create:

FlowExecutionRequirementPriority
Password-or-passkey (top level)auth-cookieALTERNATIVE0
auth-spnegoDISABLED1
identity-provider-redirectorALTERNATIVE2
forms sub-flowALTERNATIVE3
forms sub-flowauth-username-password-formALTERNATIVE2
webauthn-authenticator-passwordlessALTERNATIVE3

Two ALTERNATIVEs in the forms sub-flow offers the choice. Keycloak renders the lowest-priority execution it can execute and exposes alternatives through the "Try another way" control. auth-username-password-form is deliberately first (lower priority): it works for any user with a password, ensuring the default screen is never a dead end. The passkey authenticator sits behind "Try another way."

webauthn-authenticator-passwordless (priority 3) is the passwordless WebAuthn authenticator — do not confuse it with webauthn-authenticator (the second-factor variant). The passwordless variant allows username-less authentication with discoverable credentials.

Without the atomic-flows extension

importAuthenticationFlow 404s without the extension. Offer it as the one-shot path, but document the manual component sequence:

  1. addFlow(alias="Password-or-passkey")
  2. addSubFlow(parentFlowAlias="Password-or-passkey", alias="Password-or-passkey forms", priority=3)
  3. addAuthenticator on the top-level flow: auth-cookie priority 0, auth-spnego priority 1, identity-provider-redirector priority 2
  4. addAuthenticator on the forms sub-flow: auth-username-password-form priority 2, webauthn-authenticator-passwordless priority 3
  5. setExecutionRequirement — ALTERNATIVE for all except auth-spnego (DISABLED)
  6. bindRealmAuthenticationFlow / bindClientAuthenticationFlow

Pass priority explicitly on every call. Read the order back with listFlowExecutions before binding — nothing errors on a wrong order.

Step 2 — The WebAuthn passwordless policy

setWebAuthnPasswordlessPolicy configures the passwordless WebAuthn policy (separate from the realm's ordinary second-factor WebAuthn policy). Critical fields:

  • rpId — the realm's serving hostname, no scheme/port/path. If the realm is reachable at multiple hostnames, an empty or mismatched value fails client-side with no server error. Set it to the hostname browsers actually navigate to.
  • requireResidentKey: "Yes" — required for passwordless/discoverable credentials to work without a username entry step.

userVerificationRequirement of "preferred" or "required" is recommended.

Call getWebAuthnPasswordlessPolicy after setting to confirm values landed.

Step 3 — Bind and confirm

bindRealmAuthenticationFlow (realm-wide) or bindClientAuthenticationFlow (specific client), then getAuthenticationBindings to verify.

Step 4 — Verifying this actually works

No tool reports "password-or-passkey login is working". Configuration can look perfect and still fail at the ceremony (a wrong rpId is the classic). Both methods have to be driven, and one of them can't be driven by an HTTP client at all:

MethodHow to verifyTooling
PasswordStart an authorization-code login, POST username + password to the form's action URL, expect a 302 to redirect_uri carrying a codePlain HTTP client
PasskeyRegister via webauthn-register-passwordless, then log in through "Try another way" → the #authenticateWebAuthnButton control, expect the same 302 with a code — without entering a passwordReal browser required

A passkey ceremony is navigator.credentials.create() / .get() — actual client-side JavaScript. Scripting it needs a headless browser with a CDP virtual authenticator (WebAuthn.enable + addVirtualAuthenticator, e.g. Playwright); no HTTP client can fake the crypto exchange. If no browser is available, report the passkey half as unverified rather than inferring it from configuration.

The decisive check is that the two methods are alternatives, not two factors:

  • A user with no passkey must complete login with the password alone. If the passkey step is REQUIRED (or the password form is), this flow is password-then-passkey 2FA, and this user is stuck after a correct password — the most likely wrong outcome here, and it looks entirely correct in the admin console.
  • A user with a passkey must complete login without typing a password.
  • A wrong password must still be rejected — no code, the form re-renders with an error. A passkey path does not make the password optional for users who choose it.

Also confirm the choice is actually offered: the login page should present the username/password form and a "Try another way" control leading to the passkey option. If only one is reachable, read the order and requirements back with listFlowExecutions; mixing ALTERNATIVE with REQUIRED at the same level makes Keycloak ignore the alternatives (see flow-execution-order.md).

Two client-side details that otherwise cost an afternoon:

  • Keycloak sets AUTH_SESSION_ID and KC_RESTART as Secure; SameSite=None. Browsers send them over http://localhost anyway (loopback is a secure context); most HTTP client libraries will not, and every form POST then returns 400 "Cookie not found." Clear the flag on each response (cookie.secure = False in Python requests).
  • A user who has completed a passkey registration and one who hasn't are shown different things by the same flow. Test both populations, or a check passes for one and fails for the other.

Optional — bootstrap passkey enrollment

For users who want to transition from password to passkey: findUser → sendRequiredActionEmail with webauthn-register-passwordless. That sends an action-token email, so realm SMTP must be configured first, or the call succeeds and no mail arrives. A user who can already sign in with a password can instead be given the required action on their account directly, with no mail — see admin:credential-enrollment for which mechanism fits which user.

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