p2-inc/keycloak-skills / benchmarks/keycloak-password-or-passkey-login/environment/skills/passwordOrPasskeyLoginRest
passwordOrPasskeyLoginRest
UnverifiedConfigure username/password OR a passkey as alternative first-factor methods on one Keycloak login page, via raw Admin REST. 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 REST
What this is
One browser flow offering two alternative first-factor authentication methods side by side:
traditional username and password, and passkey (WebAuthn passwordless). The user chooses
either path at login time. Unlike admin:zero-password-login, the password is not removed —
it remains a fully supported authentication path. Unlike admin:passwordless-passkey, the
password is not eliminated — passkey is an additional option.
This is the "password with passkey option" pattern for gradual migration: keep existing password infrastructure while offering passkey as a modern alternative.
Security note: accounts support both credential types. The presence of a passkey does not prevent password login, and vice versa. User security depends on which credential they actually use.
BASE=http://localhost:8080/auth
ADMIN_TOKEN=$(curl -s -X POST "$BASE/realms/master/protocol/openid-connect/token" \
-d client_id=admin-cli -d grant_type=password \
-d username=<admin-user> -d password=<admin-password> \
| jq -r .access_token)
H="Authorization: Bearer $ADMIN_TOKEN"
REALM=<realm>
FLOW='Password-or-passkey'
SUB='Password-or-passkey forms'
The flow shape
| Flow | Execution | Requirement | Priority |
|---|---|---|---|
Password-or-passkey (top level) | auth-cookie | ALTERNATIVE | 0 |
auth-spnego | DISABLED | 1 | |
identity-provider-redirector | ALTERNATIVE | 2 | |
| forms sub-flow | ALTERNATIVE | 3 | |
| forms sub-flow | auth-username-password-form | ALTERNATIVE | 2 |
webauthn-authenticator-passwordless | ALTERNATIVE | 3 |
Key points:
auth-username-password-form(stock Keycloak) provides the password pathwebauthn-authenticator-passwordless(stock Keycloak) provides the passkey path — notwebauthn-authenticator(that's the second-factor variant)- Both are ALTERNATIVE in the same forms sub-flow, creating the "either/or" choice
Authoring via atomic import (only with the extension)
POST /admin/realms/{realm}/authentication-flow/import with the p2-inc keycloak-atomic-auth-flows
extension authors the whole flow in one call. Stock Keycloak has no such endpoint: a 404 here
means the extension is not installed, so use manual authoring
instead.
Strip ifResourceExists from the payload (the extension rejects unknown fields), and read the
generated alias back from the response (the extension hash-prefixes aliases):
cat > /tmp/password-or-passkey.json << 'EOF'
{
"flowAlias": "Password-or-passkey",
"description": "Browser flow with password or passkey as alternative first factors",
"providerId": "basic-flow",
"topLevel": true,
"builtIn": false,
"authenticationExecutions": [
{
"authenticator": "auth-cookie",
"requirement": "ALTERNATIVE",
"priority": 0,
"autheticatorFlow": false,
"userSetupAllowed": false
},
{
"authenticator": "auth-spnego",
"requirement": "DISABLED",
"priority": 1,
"autheticatorFlow": false,
"userSetupAllowed": false
},
{
"authenticator": "identity-provider-redirector",
"requirement": "ALTERNATIVE",
"priority": 2,
"autheticatorFlow": false,
"userSetupAllowed": false
},
{
"requirement": "ALTERNATIVE",
"priority": 3,
"autheticatorFlow": true,
"flowAlias": "Password-or-passkey forms",
"userSetupAllowed": false
}
],
"nestedFlows": [
{
"flowAlias": "Password-or-passkey forms",
"description": "Username/password or passkey forms",
"providerId": "basic-flow",
"topLevel": false,
"builtIn": false,
"authenticationExecutions": [
{
"authenticator": "auth-username-password-form",
"requirement": "ALTERNATIVE",
"priority": 2,
"autheticatorFlow": false,
"userSetupAllowed": false
},
{
"authenticator": "webauthn-authenticator-passwordless",
"requirement": "ALTERNATIVE",
"priority": 3,
"autheticatorFlow": false,
"userSetupAllowed": false
}
]
}
]
}
EOF
curl -s -X POST "$BASE/admin/realms/$REALM/authentication-flow/import?force=false" \
-H "$H" -H 'Content-Type: application/json' --data-binary @/tmp/password-or-passkey.json
Manual authoring (no extension)
Stock Admin REST, in this order. q URL-encodes an alias (the sub-flow's contains a space).
q() { jq -rn --arg f "$1" '$f|@uri'; }
J='Content-Type: application/json'
# 1. Top-level flow
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows" -H "$H" -H "$J" \
-d '{"alias":"Password-or-passkey","description":"Browser flow with password or passkey","providerId":"basic-flow","topLevel":true,"builtIn":false}'
# 2. The forms sub-flow is created AS an execution of the parent, in one call. Do NOT
# create it first with POST /authentication/flows: that makes a second, top-level flow
# with the same alias, this call then answers 409 Conflict, and the orphan stays behind.
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(q "$FLOW")/executions/flow" -H "$H" -H "$J" \
-d '{"alias":"Password-or-passkey forms","description":"Username/password or passkey forms","provider":"basic-flow","type":"basic-flow","priority":3}'
# 3. Leaves of the top-level flow. The add call APPENDS unless priority is sent.
for p in auth-cookie:0 auth-spnego:1 identity-provider-redirector:2; do
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(q "$FLOW")/executions/execution" -H "$H" -H "$J" \
-d "{\"provider\":\"${p%%:*}\",\"priority\":${p##*:}}"
done
# 4. Leaves of the forms sub-flow: the password form first, so it is the page users see.
for p in auth-username-password-form:2 webauthn-authenticator-passwordless:3; do
curl -s -X POST "$BASE/admin/realms/$REALM/authentication/flows/$(q "$SUB")/executions/execution" -H "$H" -H "$J" \
-d "{\"provider\":\"${p%%:*}\",\"priority\":${p##*:}}"
done
# 5. Set requirements. New executions start DISABLED, and the add calls ignore a
# "requirement" field. Change one with PUT on the flow's executions COLLECTION
# (not executions/{id}), 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 the priority to 0 and scrambles the order. A
# sub-flow's own row has no providerId; it is matched by its displayName (the alias).
set_req() { # <flow alias> <providerId or sub-flow alias> <requirement>
curl -s "$BASE/admin/realms/$REALM/authentication/flows/$(q "$1")/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/$(q "$1")/executions" -H "$H" -H "$J" --data-binary @-
}
set_req "$FLOW" auth-cookie ALTERNATIVE
set_req "$FLOW" identity-provider-redirector ALTERNATIVE
set_req "$FLOW" "$SUB" ALTERNATIVE
set_req "$SUB" auth-username-password-form ALTERNATIVE
set_req "$SUB" webauthn-authenticator-passwordless ALTERNATIVE
# auth-spnego stays DISABLED. Each PUT answers 204.
# 6. Read the whole tree back; level, position and requirement must match the table above
# before binding (top level: auth-cookie, auth-spnego, identity-provider-redirector, forms).
curl -s "$BASE/admin/realms/$REALM/authentication/flows/$(q "$FLOW")/executions" -H "$H" \
| jq -r '.[] | "\(.level) \(.index) prio=\(.priority) \(.providerId // .displayName) \(.requirement)"'
WebAuthn passwordless policy and realm SMTP
The passwordless policy is a separate block from the realm's second-factor WebAuthn policy. Set it, and the realm's outgoing mail, with one read-modify-write of the realm:
curl -s "$BASE/admin/realms/$REALM" -H "$H" \
| jq '. + {
webAuthnPolicyPasswordlessRpEntityName: "Acme Portal",
webAuthnPolicyPasswordlessRpId: "localhost",
webAuthnPolicyPasswordlessRequireResidentKey: "Yes",
webAuthnPolicyPasswordlessUserVerificationRequirement: "preferred",
smtpServer: {host: "<smtp-host>", port: "<smtp-port>", from: "<from-address>",
auth: "false", starttls: "false", ssl: "false"}
}' \
| curl -s -o /dev/null -w '%{http_code}\n' -X PUT "$BASE/admin/realms/$REALM" -H "$H" -H "$J" --data-binary @-
rpId: hostname only, no scheme/port. Must match what browsers navigate to.requireResidentKey: "Yes": required for passwordless/discoverable credentials.smtpServer: an existing user's first passkey usually arrives by an execute-actions email (below), and Keycloak refuses to send one without a sender:500"No sender address configured in the realm settings for emails". Take host, port, sender and the auth/TLS flags from the mail server you were given; every value is a string. Skip it only when no user will be enrolled by email.
Binding
# Realm-wide: browserFlow takes the flow's ALIAS
curl -s -X PUT "$BASE/admin/realms/$REALM" -H "$H" -H "$J" \
-d '{"browserFlow":"Password-or-passkey"}'
# Or one client: authenticationFlowBindingOverrides (plural) 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 '%{http_code}\n' -X PUT "$BASE/admin/realms/$REALM/clients/$CID" -H "$H" -H "$J" --data-binary @-
Verifying this actually works
No endpoint 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:
| Method | How to verify | Tooling |
|---|---|---|
| Password | Start an authorization-code login, POST username + password to the form's action URL, expect a 302 to redirect_uri carrying a code | Plain HTTP client |
| Passkey | Register via webauthn-register-passwordless, then log in through "Try another way" → the #authenticateWebAuthnButton control, expect the same 302 with a code — without entering a password | Real 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_IDandKC_RESTARTasSecure; SameSite=None. Browsers send them overhttp://localhostanyway (loopback is a secure context); most HTTP client libraries will not, and every form POST then returns400"Cookie not found." Clear the flag on each response (cookie.secure = Falsein Pythonrequests). - 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.
The passkey half needs a user who has a passkey. To give an existing user one, see
admin:credential-enrollment: a required action on the account (no mail involved) for a user who
can already sign in with a password, or an execute-actions email with
webauthn-register-passwordless — which needs the realm SMTP above:
UID_=$(curl -s "$BASE/admin/realms/$REALM/users?username=<username>&exact=true" -H "$H" | jq -r '.[0].id')
curl -s -o /dev/null -w '%{http_code}\n' -X PUT -H "$H" -H "$J" \
"$BASE/admin/realms/$REALM/users/$UID_/execute-actions-email?client_id=<client-id>&redirect_uri=<url-encoded-redirect-uri>" \
-d '["webauthn-register-passwordless"]'
# 204 = sent. The user completes the registration in a browser from the emailed link.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |