Skip to content

Passkeys (WebAuthn / FIDO2)

Give users the strongest, simplest sign-in available — phishing-resistant, password-free, and backed by hardware.

What it is

HelixIAM supports WebAuthn / FIDO2 passkeys as a first-class authentication factor. A passkey is a cryptographic credential bound to the user's device and to your origin. Because the private key never leaves the authenticator and the signature is scoped to your domain, passkeys are phishing-resistant by design — there is no shared secret to steal, replay, or relay.

Helix works with both authenticator types:

  • Platform authenticators — built into the user's device (Face ID, Touch ID, Windows Hello, Android biometrics).
  • Roaming authenticators — portable security keys that move between devices over USB, NFC, or Bluetooth.

Why it matters

  • Phishing-resistant — credentials are cryptographically bound to your origin, so a lookalike site cannot harvest them.
  • No shared secret — nothing to breach, reuse, or enter incorrectly.
  • Low friction — a biometric or a key tap replaces typing codes.
  • Primary or step-up — usable as the main sign-in factor or as a strong step-up second factor inside a flow.

A secure origin is required

WebAuthn only operates over a secure (https) origin. Passkeys cannot be registered or used over plain HTTP. Ensure your sign-in pages are served over TLS before enabling this factor.

How it works

  1. Registration — the user's authenticator generates a key pair; the public key is registered with Helix and the private key stays on the device.
  2. Authentication — Helix issues a challenge; the authenticator signs it (after a local biometric or key-tap gesture) and returns the signature.
  3. Verification — Helix verifies the signature against the registered public key and the request origin, completing the factor.

Enrolment

Users enrol passkeys from the account console:

  1. The user opens their account console and chooses to add a passkey.
  2. The browser prompts them to use a platform authenticator (biometric) or a roaming security key.
  3. The credential is registered to your realm and ready to use at the next sign-in.

New passkeys are registered as discoverable credentials, so they also work for a passwordless first step. There is no required action for passkey enrolment; users add a passkey themselves in the account console.

Use in a flow

Add a passkey step to a sign-in journey as either:

  • the first step (Passkey (passwordless)) — the sign-in page shows the passkey prompt without asking for a username first. User verification is required, and the passkey must belong to a user of the realm. The Authenticator app is not needed for this. Users can always choose Use password instead. After a passkey sign-in, second-factor steps are skipped; conditions and consent still apply.
  • a method in a stage — a second factor after the password, or a conditional step-up factor challenged only for sensitive applications or elevated risk. When an earlier step already identified the user, only that user's passkeys are offered.

Watch: add a passkey step

36 seconds, no sound. Add a passkey as a conditional step-up in a new flow and check the live preview. Recorded on the current release.

In the console

There is no separate passkey screen. A passkey is placed in a flow on the Authentication page, and a user's passkeys are listed on the user's Passkeys & codes tab.

  1. Open Authentication and pick the flow (or click New flow).
  2. For a passwordless sign-in, choose Passkey (passwordless) under First step. For a second factor or step-up, add Passkey (WebAuthn) to a stage with + method, and set the stage's When it runs to Always or Only when (a conditional step-up).
  3. Click Save changes, and bind the flow under Where this flow is used.
  4. Confirm your sign-in origin is served over https — WebAuthn will not operate over plain HTTP.
  5. Users then enrol a passkey from the account console.

Encourage a second passkey

Prompt users to register more than one passkey (for example, a phone biometric and a roaming key) so losing one device doesn't lock them out. Recovery codes provide an additional fallback — see OTP factors.

Over the API

Passkey registration and authentication are WebAuthn protocol ceremonies run in the user's browser during login or from the account console — there is no admin "add a passkey for a user" endpoint (the private key never leaves the device). From the admin API you place the passkey authenticator into a flow. The examples assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List the passkey authenticators

Both are LoA 3 — the strongest phishing-resistant factors in the registry alongside device push.

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/authenticators"
[
  { "id": "webauthn",      "displayName": "Passkey (WebAuthn)",   "factorClass": "POSSESSION", "levelOfAssurance": 3, "category": "METHOD" },
  { "id": "passkey-login", "displayName": "Passwordless passkey", "factorClass": "POSSESSION", "levelOfAssurance": 3, "category": "METHOD", "firstStepCapable": true }
]

  • webauthn — a passkey used as a second/step-up factor after another step.
  • passkey-login — a passwordless sign-in where the passkey is the sign-in (console: Passkey (passwordless)). It can be the flow's first step.

Place a passkey in a flow

Add the chosen authenticatorId to the flow's execution tree with the requirement you want (REQUIRED or CONDITIONAL). To make passkey-login the first step, put it at the top level with "requirement": "REQUIRED" and "config": {"firstStep": "true"}; a flow has at most one first step. See Authentication flows → Over the API for the PUT /flows/{alias} call.

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /authenticators List the passkey factors (webauthn, passkey-login)
GET /flows/{alias} · PUT /flows/{alias} Read / save the flow that presents the passkey step

Registration is on the protocol surface

The WebAuthn create/get ceremonies happen during login and from the account console, not via /admin.

See also