🔐
Security

Adding Passkeys to Your Website: A Practical WebAuthn Guide

19.11.2026
← All articles

Passkeys are no longer reserved for big tech. Thanks to the WebAuthn standard built into browsers, any site, from a small online shop to a training centre portal, can offer passwordless sign-in with a fingerprint or PIN. Here is how to add passkeys to an existing password-based system, and which parts to leave to a proven library.

How WebAuthn works

Three parties are involved: your server (the relying party), the browser and the authenticator, which may be a phone, laptop or USB security key. During registration the server issues a random challenge, the authenticator creates a key pair and the public key is returned. During login the server issues a fresh challenge, the authenticator signs it, and the server verifies the signature with the stored public key. The private key never leaves the device, and each key is bound to a domain called the rp ID, which defeats phishing.

Prerequisites

# PHP
composer require lbuchs/webauthn
# or
composer require web-auth/webauthn-lib

# Node.js
npm install @simplewebauthn/server @simplewebauthn/browser

Database schema

A user may have several passkeys, so store them in a separate table:

CREATE TABLE passkeys (
  id            INT AUTO_INCREMENT PRIMARY KEY,
  user_id       INT NOT NULL,
  credential_id VARBINARY(1024) NOT NULL,
  public_key    BLOB NOT NULL,
  sign_count    INT UNSIGNED NOT NULL DEFAULT 0,
  title         VARCHAR(100) NULL,
  last_used_at  DATETIME NULL,
  UNIQUE KEY uq_cred (credential_id(255)),
  KEY idx_user (user_id)
);

A decreasing non-zero sign_count may indicate a cloned authenticator, but synced passkeys often always report 0, so do not treat zero as an error.

Registration in the browser

A signed-in user clicks "Add passkey". The page fetches options, calls navigator.credentials.create() and posts the result back. The server keeps the one-time challenge in the session:

// convert base64url to ArrayBuffer and back
const b64uToBuf = s => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0)).buffer;
const bufToB64u = b => btoa(String.fromCharCode(...new Uint8Array(b))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

const opts = await fetch('/webauthn/register-options', { method: 'POST' }).then(r => r.json());

const cred = await navigator.credentials.create({
  publicKey: {
    challenge: b64uToBuf(opts.challenge),
    rp: { name: 'Misol Shop', id: 'misol.uz' },
    user: { id: b64uToBuf(opts.userId), name: opts.email, displayName: opts.name },
    pubKeyCredParams: [
      { type: 'public-key', alg: -7 },   // ES256
      { type: 'public-key', alg: -257 }  // RS256
    ],
    authenticatorSelection: { residentKey: 'required', userVerification: 'preferred' },
    timeout: 60000
  }
});

await fetch('/webauthn/register-verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: cred.id,
    clientDataJSON: bufToB64u(cred.response.clientDataJSON),
    attestationObject: bufToB64u(cred.response.attestationObject)
  })
});

residentKey: 'required' makes the credential discoverable. Use random bytes for user.id, never an email address or phone number.

Server-side verification

Make sure your library checks that the challenge matches the session, the origin is https://misol.uz, the rp ID hash matches your domain and the user-presence flag is set. Then store the public key and credential ID, and delete the challenge whether verification succeeded or failed.

Sign-in with autofill

With conditional UI, saved passkeys appear in the username field's autofill list:

<input type="text" name="username" autocomplete="username webauthn">

const opts = await fetch('/webauthn/login-options', { method: 'POST' }).then(r => r.json());
const assertion = await navigator.credentials.get({
  mediation: 'conditional',
  publicKey: {
    challenge: b64uToBuf(opts.challenge),
    rpId: 'misol.uz',
    userVerification: 'preferred'
  }
});
// assertion.id, response.clientDataJSON, response.authenticatorData,
// response.signature and response.userHandle are sent to the server

The server finds the record by credential ID, verifies the signature, updates sign_count and last_used_at, and opens a normal session.

Example: a gradual rollout at a training centre

An English school in Samarkand runs a student portal on example.uz. In month one it added an optional "Add passkey" button and autofill while passwords kept working, plus a named list of keys with a delete button. From month two, teachers and admins, who can change grades and payments, had to use a passkey or another second factor.

Common mistakes

Choosing www.misol.uz as the rp ID and later moving to the bare domain; reusing challenges or keeping them only in the browser; and having no recovery path, or one weaker than the passkey itself. Also show friendly errors: NotAllowedError usually just means the user cancelled or the prompt timed out.

Related articles

🛡️ Securing a DLE Site: Licensing, the Admin Panel and the uploads Folder 🖱️ Clickjacking: protecting your site with X-Frame-Options and CSP 🧩 Outdated plugins: the most common reason websites get hacked 🚪 Does Changing the SSH Port Help? Myth vs Reality
🌐 Language
🇺🇿 O'zbek 🇺🇿 Ўзбек 🇷🇺 Русский 🇬🇧 English ✓