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
- HTTPS. WebAuthn only runs in a secure context;
localhostis allowed for development. sayt.uz hosting installs a free, auto-renewing Let's Encrypt certificate. - Correct rp ID. Usually the registrable domain, e.g.
misol.uz;shop.misol.uzmay use it, but not the other way round. - A server library. Parsing CBOR and COSE by hand is error-prone.
# 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.