What is WebAuthn?

WebAuthn (Web Authentication) is a web standard, published by the World Wide Web Consortium (W3C) together with the FIDO Alliance, that lets a website ask your browser to prove who you are using a physical device — a fingerprint sensor, a face scan, a PIN tied to your laptop, or a small USB/NFC security key — instead of a typed password. It is the technology behind the “passkey” buttons you now see on Google, Apple, Amazon, and thousands of other sites. WebAuthn is part of a broader specification called FIDO2, which pairs WebAuthn (the browser-to-website part) with a companion protocol called CTAP (Client to Authenticator Protocol, the browser-to-device part).

Why does WebAuthn exist?

Passwords fail in three predictable ways: people reuse them across sites, attackers steal them through fake “phishing” login pages that look real, and databases holding millions of passwords get breached and leaked. WebAuthn was designed to remove all three failure modes at once. It uses public-key cryptography — a mathematical technique where a matched pair of keys is generated: a private key that never leaves your device, and a public key that is shared freely with the website. Because the private key never travels over the network and never gets typed anywhere, it cannot be phished, leaked from a server breach, or reused across sites — each site gets a completely different key pair.

Where does Keycloak fit in?

Keycloak is a free, open-source Identity and Access Management (IAM) server originally built by Red Bear engineers and now an independent Cloud Native Computing Foundation project. Its job is to be the single front door that every application in a company routes its login through, instead of each application inventing its own login page and password database. Keycloak already understood usernames, passwords, one-time codes, and social logins (Google, GitHub, and so on); WebAuthn support means Keycloak can now also stand at that front door and say “show me your fingerprint” instead of “type your password,” while every connected application keeps working exactly the same way.

Key vocabulary, explained simply

At a high level, four parties are involved whenever someone logs into a Keycloak-protected application using WebAuthn: the user’s browser, the authenticator (the fingerprint sensor or security key), the Keycloak server acting as the Relying Party, and the application the user is actually trying to reach (called the “client” in Keycloak’s vocabulary). Keycloak itself is broken into a few internal pieces that specifically handle WebAuthn.

graph TB
    U[User] -->|touches sensor| A[Authenticator
fingerprint / security key]
    A -->|CTAP protocol| B[Browser
WebAuthn API]
    B -->|HTTPS / JavaScript| K[Keycloak Server]
    K --> AF[Authentication Flow Engine]
    K --> CS[Credential Store
public keys only]
    K --> AE[Admin Event Logger]
    K -->|issues token| APP[Protected Application]
    U -->|opens| APP
    APP -->|redirects to login| K
    

Component breakdown

Why does Keycloak use the browser’s own API instead of building its own?

WebAuthn deliberately lives inside the browser itself (Chrome, Safari, Firefox, Edge all ship it natively) rather than as a plugin a website installs. This matters architecturally: Keycloak never touches your fingerprint data, never sees your device’s secure hardware, and never processes biometric information at all. It only ever receives a signed mathematical proof from the browser. This is why Keycloak’s WebAuthn feature can be enabled with configuration, not custom biometric-handling code — the heavy lifting is done by the operating system and the browser, and Keycloak’s role is closer to a strict inspector checking a signed document than a biometric processor.

Registration — creating a new credential

When a user first turns on WebAuthn for their account, Keycloak’s server generates a random challenge — essentially a one-time, unguessable string of bytes — and sends it to the browser along with some details about the user and the realm. The browser passes this to the authenticator through the CTAP protocol. Inside the authenticator’s secure hardware, a brand-new public/private key pair is generated specifically for this Keycloak realm. The private key is sealed inside the device and will never be exported. The authenticator signs the original challenge using the new private key, producing proof that this exact device generated this exact key pair right now, and sends the public key plus the signed proof back through the browser to Keycloak. Keycloak verifies the signature, checks the attestation (if configured to), and stores the public key against the user’s account.

Authentication — proving you still hold the private key

On every future login, Keycloak again generates a fresh, random challenge. This time it also sends the list of credential IDs already registered to that user (or, for fully passwordless “discoverable” logins, no list at all — more on this in the next chapter). The browser forwards the challenge to the authenticator. The user unlocks the authenticator (touch, face, PIN), the device locates the matching private key, and signs the challenge with it. This signed assertion travels back to Keycloak, which looks up the matching public key it stored during registration and mathematically verifies that the signature could only have been produced by the corresponding private key. If it checks out, the user is authenticated — without a password ever being typed, transmitted, or even existing for this login method.

The sign-counter — Keycloak’s cloning detector

Every WebAuthn authenticator maintains a small internal counter that increases by at least one on every successful authentication. Keycloak stores the last counter value it saw for each credential. If a login arrives with a counter value equal to or lower than the last one stored, Keycloak treats this as a red flag — it usually means the private key has somehow been cloned onto a second, malicious device, since a genuine, single physical authenticator’s counter can only go up. Keycloak can be configured to reject such logins outright.

Step-by-step: what happens internally, in order

sequenceDiagram
    participant User
    participant Browser
    participant Authenticator
    participant Keycloak
    participant App as Application

    User->>App: Clicks "Login"
    App->>Keycloak: Redirects to login page
    Keycloak->>Browser: Sends challenge + credential options
    Browser->>Authenticator: navigator.credentials.get()
    Authenticator->>User: Prompts fingerprint / PIN
    User->>Authenticator: Provides biometric / PIN
    Authenticator->>Browser: Signed assertion
    Browser->>Keycloak: Sends signed assertion
    Keycloak->>Keycloak: Verifies signature vs stored public key
    Keycloak->>App: Redirects with authorization code
    App->>Keycloak: Exchanges code for tokens
    Keycloak->>App: Access token + ID token
    App->>User: Shows logged-in dashboard
    

Notice something important in that diagram: the application itself never sees the fingerprint, the private key, the assertion, or any WebAuthn detail at all. It only ever receives an authorization code and, later, standard tokens (using OpenID Connect, the protocol Keycloak speaks with applications). This separation is deliberate and central to Keycloak’s whole design — WebAuthn is a concern between the browser and Keycloak; the application only cares about the end result, a proven identity.

The lifecycle of a single credential

Two flavors of data flow: second-factor vs. passwordless

Keycloak supports WebAuthn in two distinct data-flow shapes. In second-factor mode, the browser first sends a username and password as normal, and only after that succeeds does Keycloak ask for the WebAuthn assertion — two separate round-trips, two separate proofs. In passwordless (discoverable credential) mode, the user does not type a username at all; the browser asks the authenticator “which of your stored credentials matches this website?” and the authenticator itself supplies both the identity and the signed proof in one round-trip. This is what makes true one-touch, no-typing login possible.

Common trade-off Keycloak admins must actually decide on

Origin binding — the core phishing defense

Every WebAuthn credential is cryptographically tied to a specific Relying Party ID, essentially Keycloak’s domain name. When a browser calls the WebAuthn API, the browser itself — not Keycloak, not the user, not any JavaScript on the page — enforces that the credential can only be used on that exact domain. If an attacker builds a pixel-perfect fake copy of the Keycloak login page on a different domain, the browser will refuse to release a valid signature for it, because the origin does not match what was recorded at registration. This single mechanism is why WebAuthn defeats classic phishing attacks that easily fool password-based logins.

Man-in-the-middle and replay resistance

Because every login uses a brand-new random challenge, a captured signed assertion cannot be replayed later to log in again — the old challenge will simply be rejected as stale. Combined with the requirement that Keycloak be served over HTTPS, this closes off the two classic attack patterns that plague password-based systems: credential replay and network interception.

Attestation — verifying the authenticator is genuine hardware

During registration, Keycloak can optionally demand attestation: a signed certificate, baked into the authenticator by its manufacturer, proving the device is a real, certified piece of hardware rather than software pretending to be one. High-security deployments (banking, government, healthcare) often require attestation and check it against an approved metadata list of certified authenticator models. Lower-stakes consumer applications typically accept “none” attestation for a smoother user experience, trading a small amount of assurance for broader device compatibility.

Session and token security downstream

It is worth remembering that WebAuthn only secures the login moment itself. Once Keycloak issues an OpenID Connect token to the application, standard token security practices — short expiry times, secure storage, HTTPS everywhere, and proper token revocation — still fully apply. WebAuthn strengthens the front door; it does not replace the need to also secure everything that happens after someone walks through it.

What Keycloak logs by default

Keycloak’s built-in event system records both user-facing events (like a successful or failed login) and admin events (like a configuration change). For WebAuthn, relevant event types include credential registration, credential removal, and both successful and failed WebAuthn login attempts. These events can be streamed to external systems for long-term storage and alerting, since Keycloak’s own event store is meant for short-term operational visibility rather than permanent audit trails.

Metrics worth tracking operationally

Where Keycloak’s own metrics come from

Keycloak exposes a Prometheus-compatible metrics endpoint (when the metrics feature is enabled), which reports server-level health such as request latency and thread pool usage. WebAuthn-specific business metrics, however, are typically not exposed as ready-made Prometheus counters out of the box; most production teams build these themselves by consuming Keycloak’s event stream (via a listener sent to Kafka, a SIEM, or a logging pipeline) and deriving adoption and failure metrics from the raw events.

Proven patterns

Anti-patterns to avoid

Best practices

Common mistakes