Passkey быстро набирает популярность и уже не является привилегией крупных компаний. Благодаря встроенному в браузеры стандарту WebAuthn любой сайт, например небольшой интернет-магазин или личный кабинет учебного центра, может предложить вход без пароля по отпечатку пальца или PIN-коду. Ниже разберём на примерах, как добавить passkey к существующей системе с паролями.
Как устроен процесс WebAuthn
WebAuthn работает между тремя участниками: вашим сервером (в стандарте он называется relying party), браузером пользователя и аутентификатором, то есть телефоном, ноутбуком или USB-ключом безопасности. Процесс состоит из двух этапов. При регистрации сервер создаёт случайный challenge, браузер просит у аутентификатора новую пару ключей и возвращает открытый ключ на сервер. При входе сервер снова выдаёт новый challenge, аутентификатор подписывает его закрытым ключом, а сервер проверяет подпись сохранённым открытым ключом. Закрытый ключ никогда не покидает устройство, а сам ключ привязан к домену (rp ID), поэтому фишинговый сайт им воспользоваться не сможет.
Требования перед началом
- HTTPS обязателен. WebAuthn работает только в защищённом контексте. Во время разработки исключение делается для
localhost, но на рабочем сайте нужен настоящий SSL-сертификат. - Правильный rp ID. Обычно это основной домен сайта, например
misol.uz. rp ID должен совпадать с доменом текущей страницы или быть его родительской частью, поэтому страницаshop.misol.uzможет использоватьmisol.uz, а наоборот нельзя. - Библиотека на сервере. Ручной разбор подписи и данных attestation требует знания форматов CBOR и COSE.
На хостинге sayt.uz сертификат Let's Encrypt устанавливается бесплатно и продлевается автоматически, поэтому требование HTTPS обычно уже выполнено. Среди библиотек часто используют такие:
# PHP
composer require lbuchs/webauthn
# или
composer require web-auth/webauthn-lib
# Node.js
npm install @simplewebauthn/server @simplewebauthn/browser
Структура базы данных
У одного пользователя может быть несколько passkey: один на телефоне, другой на рабочем компьютере, третий на запасном USB-ключе. Поэтому храните их не колонкой в таблице пользователей, а в отдельной таблице. Достаточно идентификатора, открытого ключа, счётчика подписей (sign_count, помогает заметить клон) и названия:
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)
);
Регистрация: часть в браузере
Допустим, пользователь уже вошёл по паролю, а на странице профиля есть кнопка «Добавить passkey». По нажатию браузер получает параметры с сервера, вызывает navigator.credentials.create() и отправляет результат обратно на проверку. Сервер должен сохранить challenge в сессии, он используется только один раз:
// преобразование base64url в ArrayBuffer и обратно
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' делает ключ «обнаруживаемым», то есть позже пользователь сможет выбрать passkey даже без ввода логина. В качестве user.id используйте не email или телефон, а внутренний идентификатор из случайных байтов, потому что это значение хранится в аутентификаторе.
Проверка на сервере
С пришедшими данными библиотека выполняет несколько проверок, и вам нужно убедиться, что все они включены. Прежде всего challenge внутри clientDataJSON должен совпасть со значением в сессии, а origin — с https://misol.uz. Затем хеш rp ID в данных аутентификатора должен равняться хешу вашего домена, а флаг присутствия пользователя должен быть установлен. Если всё верно, библиотека вернёт открытый ключ и credential ID, и вы запишете их в таблицу. Удаляйте challenge из сессии сразу и после успешной проверки, и после ошибки.
Вход с passkey и автозаполнение
Удобнее всего на странице входа так называемый conditional UI: когда пользователь нажимает на поле логина, браузер показывает сохранённые passkey в списке автозаполнения. Для этого полю добавляется специальное значение autocomplete, а запрос отправляется заранее при загрузке страницы:
<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 и response.userHandle отправляются на сервер
На сервере по userHandle и credential ID находится нужная запись, библиотека проверяет подпись открытым ключом, после чего обновляются sign_count и last_used_at.
Пример: поэтапное внедрение в кабинете учебного центра
У центра английского языка в Самарканде на сайте example.uz есть кабинет, где ученики смотрят расписание и оплаты. Разработчик не стал делать passkey обязательным сразу. В первый месяц на странице профиля появилась кнопка «Добавить passkey», на странице входа включили автозаполнение, а пароль продолжал работать как раньше. Каждому passkey можно дать название вроде «Мой телефон Samsung» и удалить его. Для преподавателей и администраторов со второго месяца passkey или другой второй фактор стал обязательным.
Частые ошибки
Первая типичная ошибка — неверный выбор rp ID: ключ, созданный для www.misol.uz, может перестать работать после переезда на misol.uz, поэтому сразу выбирайте основной домен. Вторая — повторное использование challenge или хранение его только в браузере, что открывает дорогу атакам повтора. Третья — отсутствие запасного пути: продумайте заранее, как пользователь восстановит доступ, если потеряет единственное устройство, и следите, чтобы этот путь не оказался слабее самого passkey. А NotAllowedError обычно значит, что пользователь закрыл окно, это не проблема безопасности.