How to Implement Passkeys with WebAuthn: A Production Tutorial for Engineering and Security Teams

Passwords fail in two directions at once. They are the most common entry point for attackers, and they are also a persistent source of abandoned sign-ups and support tickets. Passkeys — credentials built on the W3C Web Authentication (WebAuthn) API and the FIDO Alliance's CTAP protocols — address both problems by replacing a shared secret with a public–private key pair that is cryptographically bound to a specific website origin.

The technology is no longer speculative. The FIDO Alliance estimates that roughly five billion passkeys were in use worldwide as of May 2026, with 90% consumer awareness and 68% of surveyed organisations having deployed or actively deploying passkeys for employee sign-in. What remains genuinely difficult is the implementation: the cryptography is the easy part, while credential lifecycle, account recovery, cross-device flows and rollout sequencing are where most projects stall.

This tutorial is written for professionals who have to ship. It walks through the WebAuthn ceremonies end to end, gives a concrete server-side verification checklist, explains the design decisions that determine whether adoption succeeds, and separates what is standardised and stable from what is still moving. Readers will finish with an implementation sequence they can take to a sprint planning session, a set of measurable rollout criteria, and a clear view of the failure modes that cause passkey projects to be quietly rolled back.

Executive summary

• Passkeys are WebAuthn credentials: an origin-bound key pair where the private key never leaves the authenticator and the server stores only a public key. This structurally removes phishing, credential stuffing and server-side password breach from the threat model.
• Two credential types matter operationally: synced passkeys, which a credential provider replicates across a user's devices, and device-bound passkeys, which remain on one authenticator such as a hardware security key. They carry different assurance and recovery properties and should be chosen deliberately.
• NIST published SP 800-63B-4 as final on 31 July 2025, superseding SP 800-63B, and integrated its earlier interim guidance on syncable authenticators into the revised text. Teams working to a federal or federal-adjacent baseline should read the current revision rather than the withdrawn supplement.
• WebAuthn Level 3 was published as a Candidate Recommendation Snapshot on 26 May 2026, and W3C announced on 20 July 2026 that it had proposed advancing the specification to Recommendation status. Level 3 formalises features many teams already use, including client capability detection and the Signal API.
• The largest implementation risk is not cryptographic. It is account recovery: a passkey deployment that leaves a phishable recovery channel (SMS codes, emailed magic links) inherits the weakness of that channel.
• Adoption is driven overwhelmingly by prompt placement and timing, not by the presence of a settings page toggle. Instrument the enrolment funnel before optimising anything else.
• Reported operational benefits are real but largely self-reported by deploying vendors; treat published success-rate figures as directional benchmarks, not guarantees for your user base.
• A staged rollout — passkey as an additional factor, then as a primary option, then as the default, with passwords retired last — is the pattern that most published deployments describe.

Why this matters now

Two independent bodies of evidence support the business case, and each has limitations worth naming.

The first is peer-reviewed. Google engineers published a two-year deployment analysis of FIDO security keys at Financial Cryptography 2016, reporting that 3% of one-time-password authentications failed during the study period while security key authentications produced no observed failures, alongside reduced authentication time and lower support costs. That study predates passkeys and covers second-factor hardware keys inside a single large employer, so it generalises to the mechanism rather than to consumer synced credentials.

The second is industry-reported. The FIDO Alliance's Passkey Index, published in October 2025, aggregates data from member companies including Amazon, Google, Microsoft, PayPal, Target and TikTok, and reports that 36% of accounts at contributing companies have a passkey enrolled and 26% of sign-ins use one, with an average sign-in time of 8.5 seconds — a 73% reduction against other methods. These figures are self-reported by organisations with an interest in the outcome and are drawn from a small number of very large consumer platforms; they are a useful benchmark ceiling, not a forecast for a mid-size B2B application.

The security case is best illustrated by a documented incident. In August 2022, Cloudflare disclosed that its employees were targeted by a phishing campaign resembling the one that had compromised Twilio a day earlier. Some employees entered credentials on the attacker's page, but the attack failed because hardware security keys were required to access all internal applications, and no Cloudflare systems were compromised. The mechanism that saved them — origin binding — is exactly the property passkeys inherit.

Technical foundations

The two ceremonies

WebAuthn defines two flows, both mediated by the browser and both anchored to a server-generated challenge.

Registration (navigator.credentials.create) — the server issues a challenge and relying party (RP) parameters; the authenticator generates a key pair scoped to the RP ID, keeps the private key, and returns an attestation object containing the public key and metadata. The server stores the credential ID, public key, signature counter and, where relevant, the authenticator's AAGUID.

Authentication (navigator.credentials.get) — the server issues a fresh challenge; the authenticator signs over the client data and authenticator data after verifying the user (biometric, PIN or gesture); the server verifies the signature against the stored public key.

The security property that makes this phishing-resistant is that the browser, not the user, decides which credential applies. The signed client data includes the true origin, and the authenticator will only produce a signature for a credential whose RP ID matches. A convincing lookalike domain cannot elicit a usable assertion, because the credential simply does not exist for that origin.

Figure 1 — brief for the design team

Figure 1. WebAuthn registration and authentication ceremonies

Purpose: show, in one view, which party holds which secret and where origin binding is enforced.

Layout: two horizontal swimlane sequences stacked vertically, sharing four columns labelled User, Authenticator / Credential Provider, Browser (WebAuthn client), Relying Party Server.

Top sequence (Registration): Server → Browser: "challenge + RP ID + user handle"; Browser → Authenticator: "create credential"; Authenticator → User: "verify (biometric / PIN)"; Authenticator → Browser: "public key + credential ID + attestation"; Browser → Server: "attestation response"; Server: terminal box "verify challenge, origin, RP ID hash, flags; store public key".

Bottom sequence (Authentication): Server → Browser: "new challenge"; Browser → Authenticator: "credential request for this origin"; Authenticator → User: "verify"; Authenticator → Browser: "signed assertion"; Browser → Server: "assertion"; Server: terminal box "verify signature against stored public key".

Visual hierarchy: shade the Authenticator column to indicate the private key never crosses its boundary; place a lock icon with the caption "private key never leaves this boundary". Use a distinct accent colour for the origin/RP ID label in both sequences.

Caption: "The relying party never receives a secret it could lose in a breach — only a public key and a signature over a challenge it issued."

Synced versus device-bound credentials

This is the single most consequential architectural choice, and it is a policy decision as much as a technical one.

Table 1. Authentication method comparison for relying parties

Table compiled from the specification behaviour described in the WebAuthn Level 3 draft and NIST SP 800-63B-4. "Context-dependent" reflects that assurance depends on the provider's sync security and on your own risk model.

Step-by-step implementation

Step 1 — Fix your RP ID before writing any code

The RP ID is a domain string that permanently scopes every credential you issue. Choosing app.example.com when you may later need example.com and accounts.example.com is an expensive, hard-to-reverse mistake, because credentials cannot be re-scoped after creation. Register at the highest domain you legitimately control and expect to keep.

For genuinely multi-domain products (for example, country-specific storefronts), WebAuthn Level 3 defines Related Origin Requests, which let a set of origins share one RP ID by publishing an allowlist at /.well-known/webauthn on the RP ID domain. The specification sets a low minimum for the number of distinct labels clients must support, so treat it as a small allowance for related properties rather than a substitute for federated single sign-on.

Step 2 — Use a maintained server library

Do not hand-roll CBOR parsing, COSE key decoding or attestation validation. Mature open-source libraries exist for Java, .NET, Go, Python, Rust and Node.js, and they encode years of accumulated edge-case handling. Your engineering value is in the ceremony orchestration, not in re-implementing signature verification.

Step 3 — Registration options that produce usable passkeys

// Server-issued options, simplified. The challenge must be
// cryptographically random, single-use, and bound to this session.
const options = {
  rp: { id: "example.com", name: "Example" },
  user: {
    id: userHandle,          // opaque, stable, NOT an email address
    name: "a.khan@example.com",
    displayName: "Aisha Khan"
  },
  challenge,
  pubKeyCredParams: [
    { type: "public-key", alg: -7 },    // ES256
    { type: "public-key", alg: -257 }   // RS256
  ],
  authenticatorSelection: {
    residentKey: "required",            // discoverable credential
    userVerification: "preferred"
  },
  excludeCredentials: existingCredentials,
  timeout: 60000
};

Four details do most of the work. Set residentKey: "required" so the credential is discoverable and can be used without the user first typing a username. Use an opaque, stable user.id; user handles may be exposed to the credential provider and should not carry personal data. Populate excludeCredentials to prevent silent duplicate registrations on the same authenticator. Prefer userVerification: "preferred" unless a specific control requires "required" — over-constraining here is a common cause of unnecessary failures on otherwise capable devices.

Step 4 — Verify rigorously on the server

Client-side checks are advisory. The server must independently validate every response.

Table 2. Server-side verification checklist

Two notes. Signature counters are not reported by many synced credential providers and will legitimately be zero; treat regression checks as applicable only where counters are non-zero. Attestation is genuinely useful for workforce deployments that must restrict enrolment to approved authenticator models via AAGUID, and it is largely unnecessary — and privacy-sensitive — for consumer sign-in.

Step 5 — Make sign-in feel automatic with conditional mediation

Conditional mediation ("autofill UI") surfaces available passkeys inside the browser's normal username field rather than as an interrupting dialogue. This is the single highest-leverage UX decision in a consumer deployment.

if (window.PublicKeyCredential?.isConditionalMediationAvailable) {
  const available = await PublicKeyCredential.isConditionalMediationAvailable();
  if (available) {
    const assertion = await navigator.credentials.get({
      publicKey: { challenge, rpId: "example.com" },
      mediation: "conditional"   // resolves only if the user picks a passkey
    });
    // send assertion to /login for verification
  }
}

Mark the username input with autocomplete="username webauthn". WebAuthn Level 3 also standardises PublicKeyCredential.getClientCapabilities(), which returns an object indicating whether specific client capabilities and extensions are supported, so relying parties can tailor sign-in and sign-up interfaces accordingly — a cleaner alternative to accumulating user-agent heuristics.

Step 6 — Design recovery before you launch, not after

A passkey deployment is only as phishing-resistant as its weakest recovery path. If an attacker can reset an account with an SMS code, the passkey is decorative. Practical options, in rough order of assurance:

1. A second registered passkey on a different authenticator — the strongest and simplest answer; prompt for it at enrolment, not later.
2. Federated identity or an enterprise IdP that is itself passkey-protected.
3. Human-verified recovery with identity proofing, for high-value accounts.
4. Time-delayed recovery with notification, which raises attacker cost even when the channel is weaker.

Whatever you choose, log it, rate-limit it and monitor it as a distinct attack surface.

Step 7 — Keep server state and provider state in sync

Users delete credentials from their password manager; administrators revoke them server-side. Either drift leaves users staring at a passkey that no longer works. The WebAuthn Signal API addresses this: it lets relying parties signal existing credentials to connected passkey providers so that revoked or unknown credentials can be updated or removed, and updated usernames and display names can be pushed, via methods including signalUnknownCredential, signalAllAcceptedCredentials and signalCurrentUserDetails. Chrome supports these methods across desktop platforms and Android; support elsewhere is still uneven, so treat the API as progressive enhancement and keep a clear server-side error path for unknown credentials.

Step 8 — Roll out in stages and measure

Sequence that most published deployments describe: (1) enable passkeys as an optional additional factor; (2) offer passkey as a primary sign-in option with password fallback; (3) prompt eligible users at sign-in and sign-up; (4) make passkey the default for new accounts; (5) retire passwords for cohorts that meet coverage thresholds.

Instrument at minimum: enrolment prompt impressions, enrolment completion rate by prompt placement, passkey sign-in share, ceremony failure codes, fallback rate to password, and password-reset ticket volume. Prompt placement is consistently reported to explain more variance in enrolment than industry or device mix — the settings page is where passkey programmes go to be ignored.

Latest developments

Dated, verifiable movement as of 4 August 2026:

• 26 May 2026 — WebAuthn Level 3 was published as a Candidate Recommendation Snapshot, scheduled to remain at that stage at least until 23 June 2026 to gather feedback.
• 20 July 2026 — W3C announced it had proposed advancing WebAuthn Level 3 to Recommendation status. At publication the specification is not yet a W3C Recommendation; Level 2 remains the most recent Recommendation-status version.
• 31 July 2025 — NIST SP 800-63B-4 was published as final, superseding SP 800-63B; the earlier syncable-authenticator supplement SP 800-63Bsup1 was withdrawn on 1 August 2025 and superseded in its entirety by SP 800-63B-4.
• 14 August 2025 — the FIDO Alliance published Credential Exchange Format (CXF) as a Proposed Standard specification, defining a normative structure for exporting credentials between providers. Its companion Credential Exchange Protocol (CXP), which governs the encrypted transfer itself, has progressed more slowly; vendor reports indicate early platform implementations of the format, but relying parties should treat provider-to-provider portability as an emerging capability rather than a shipped guarantee.
• 7 May 2026 — the FIDO Alliance released its State of Passkeys 2026 report, based on parallel Sapio Research studies of 11,000 consumers and 1,400 workforce decision-makers across ten countries conducted in April 2026, with margins of error of ±0.9 and ±2.6 percentage points respectively. The same report notes a constraint worth quoting to executives: 57% of organisations still rely on phishable authentication methods for employees' primary day-to-day sign-in.

Common myths, examined

Table 3. Frequently misunderstood claims about passkeys

Mistakes that recur in production: choosing an RP ID that cannot expand; omitting excludeCredentials; requiring userVerification: "required" without cause; storing the credential ID in a case- or encoding-sensitive way that breaks lookups; and treating ceremony errors as a single generic failure instead of distinguishing "no credential available" from "user cancelled" from "verification failed."

Practical takeaways

For engineering leads. Timebox a spike to prove the two ceremonies against a maintained library in week one. Spend the remaining effort on recovery design, error taxonomy and telemetry — that is where the schedule risk actually lives.

For security architects. Write down the assurance level each credential type satisfies under your governing framework before enabling enrolment, and audit recovery paths as first-class controls. A phishing-resistant primary factor behind a phishable reset flow is a documentation exercise, not a security improvement.

For product managers. Treat enrolment as a funnel with placement experiments, not as a settings toggle. Measure the share of sign-ins using passkeys rather than the count of passkeys created.

For executives. Expect a multi-quarter hybrid period. The reliable near-term returns are reduced reset volume and improved sign-in completion; phishing-incident reduction accrues as coverage grows.

Key insights

1. Origin binding, not biometrics, is the property that defeats phishing.
2. The RP ID decision is effectively permanent — settle it before the first credential is issued.
3. Discoverable credentials plus conditional mediation are what make passkey sign-in feel effortless.
4. Server-side verification is non-negotiable; client checks are advisory only.
5. Signature counters are frequently zero for synced credentials and cannot carry a universal cloning check.
6. Attestation is a workforce control, not a default.
7. Recovery design determines the true security level of the deployment.
8. Credential state drifts between server and provider; the Signal API mitigates this where supported.
9. Published benefit figures are largely self-reported by large platforms — directional, not predictive.
10. Rollout sequencing and prompt placement move adoption more than any API-level choice.

Frequently asked questions

What is a passkey, in one sentence?
A passkey is a WebAuthn credential — a private key held by an authenticator and a public key held by the website — that signs a server-issued challenge and works only on the origin it was created for.

Are passkeys and WebAuthn the same thing?
No. WebAuthn is the W3C browser API; "passkey" is the user-facing term for a discoverable WebAuthn credential, typically one that a credential provider can sync across devices.

Do passkeys count as multi-factor authentication?
A passkey unlocked with user verification combines possession of the authenticator with a biometric or PIN. Whether your regulator treats that as multi-factor depends on the applicable framework; check the current text of the standard that governs you.

Can passkeys be phished?
Not through credential replay on a lookalike domain, because the browser will not release a signature for the wrong origin. Attacks shift to session token theft, malware and support-desk social engineering.

What happens if the user loses their device?
With a synced passkey, the credential is recoverable through the provider's account recovery. With a device-bound passkey, the user needs a second registered authenticator — which is why prompting for one at enrolment matters.

Do I still need passwords?
Most organisations keep them during a hybrid phase. Retire them per cohort once passkey coverage and recovery paths are proven.

How do users sign in on a device that has no passkey?
Through the cross-device flow: the desktop shows a QR code and the phone approves over a proximity-verified channel, so the credential stays on the phone.

Should I require user verification?
Prefer "preferred" unless a specific control requires otherwise; requiring it narrows the set of usable authenticators without always improving assurance.

Do I need attestation?
Only if you must restrict enrolment to approved authenticator models — typically a workforce or regulated-access requirement.

Why is the signature counter zero?
Many synced credential providers do not maintain one. Apply regression checks only where the counter is non-zero.

Can one passkey work across several of my domains?
Within limits, using Related Origin Requests defined in WebAuthn Level 3, which relies on an allowlist file published on the RP ID domain. It suits closely related properties, not general single sign-on.

Can users move passkeys between password managers?
Portability is emerging. The FIDO Alliance published the Credential Exchange Format as a Proposed Standard in August 2025; the companion transfer protocol and broad provider support are still maturing.

How long does implementation take?
The ceremonies are typically days of work with a good library. Recovery design, migration, telemetry and staged rollout are the multi-sprint items.

What should I measure to know it is working?
Share of sign-ins completed with a passkey, enrolment completion by prompt placement, ceremony failure taxonomy, fallback rate and password-reset ticket volume.

Is WebAuthn Level 3 final?
Not at the time of writing. W3C proposed advancing it to Recommendation status on 20 July 2026; the widely implemented features it standardises are already available in major browsers.

Glossary

• AAGUID — an identifier for an authenticator model, used to enforce allowlists of approved devices.
• Attestation — a signed statement about the authenticator's provenance, returned at registration.
• Authenticator — the component holding the private key: a platform authenticator on a phone or laptop, or a roaming security key.
• CTAP — Client to Authenticator Protocol; the FIDO specification governing browser-to-authenticator communication.
• Conditional mediation — the "autofill" presentation of available passkeys inside a normal input field.
• CXF / CXP — FIDO Alliance specifications for the format and transfer protocol used to move credentials between providers.
• Discoverable credential — a credential the authenticator can present without the server first supplying its ID; the basis of usernameless sign-in.
• Relying Party (RP) / RP ID — the service authenticating the user, and the domain string scoping its credentials.
• Signal API — WebAuthn Level 3 methods that let a relying party inform a credential provider about credential and user-detail changes.
• Synced passkey — a credential replicated across a user's devices by a credential provider.
• User Verification (UV) — confirmation of the user's presence and identity by the authenticator via biometric, PIN or gesture.

References

Standards and specifications

Bradley, J., Hodges, J., Jones, M. B., Kumar, A., Lindemann, R., & Lundberg, E. (Eds.). (2026). Web Authentication: An API for accessing public key credentials — Level 3 (W3C Candidate Recommendation Snapshot, 26 May 2026). World Wide Web Consortium. https://www.w3.org/TR/webauthn-3/

FIDO Alliance. (2025). Credential Exchange Format (CXF) (Proposed Standard specification, 14 August 2025). https://fidoalliance.org/specifications/

World Wide Web Consortium. (2026, July 20). Proposed advancement of Web Authentication: An API for accessing public key credentials Level 3 to W3C Recommendation. https://www.w3.org/news/2026/proposed-advancement-of-webauthn-3-to-w3c-recommendation/

Government sources

National Institute of Standards and Technology. (2025). Digital identity guidelines: Authentication and authenticator management (NIST SP 800-63B-4). U.S. Department of Commerce. https://doi.org/10.6028/NIST.SP.800-63B-4

National Institute of Standards and Technology. (2024). Incorporating syncable authenticators into NIST SP 800-63B (NIST SP 800-63Bsup1; withdrawn 1 August 2025, superseded by SP 800-63B-4). U.S. Department of Commerce. https://csrc.nist.gov/pubs/sp/800/63/b/sup/final

Office of Management and Budget. (2022). Moving the U.S. Government toward zero trust cybersecurity principles (Memorandum M-22-09). Executive Office of the President.

Conference papers

Lang, J., Czeskis, A., Balfanz, D., Schilder, M., & Srinivas, S. (2017). Security keys: Practical cryptographic second factors for the modern web. In J. Grossklags & B. Preneel (Eds.), Financial Cryptography and Data Security (FC 2016), Lecture Notes in Computer Science (Vol. 9603, pp. 422–440). Springer. https://doi.org/10.1007/978-3-662-54970-4_25

Lyastani, S. G., Schilling, M., Neumayr, M., Backes, M., & Bugiel, S. (2020). Is FIDO2 the kingslayer of user authentication? A comparative usability study of FIDO2 passwordless authentication. In 2020 IEEE Symposium on Security and Privacy (SP) (pp. 268–285). IEEE.

Industry reports

FIDO Alliance. (2025). Passkey Index, October 2025. https://fidoalliance.org/wp-content/uploads/2025/10/FIDO-Passkey-Index-October-2025.pdf

FIDO Alliance. (2026, May 7). Five billion passkeys: FIDO Alliance reports mainstream global usage on World Passkey Day 2026. https://fidoalliance.org/fido-alliance-reports-accelerating-global-passkey-adoption-on-world-passkey-day-2026/

Official documentation and other authoritative sources

Cloudflare. (2022, August 9). The mechanics of a sophisticated phishing scam and how we stopped it. https://blog.cloudflare.com/2022-07-sms-phishing-attacks/

Google. (2026). Keep passkeys consistent with credentials on your server with the Signal API. Chrome for Developers. https://developer.chrome.com/docs/identity/webauthn-signal-api

Mozilla. (2026). PublicKeyCredential: getClientCapabilities() static method. MDN Web Docs. https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/getClientCapabilities_static