🔐
Безопасность

Как добавить passkey на свой сайт: практическое руководство по WebAuthn

19.11.2026
← Все статьи

Passkey быстро набирает популярность и уже не является привилегией крупных компаний. Благодаря встроенному в браузеры стандарту WebAuthn любой сайт, например небольшой интернет-магазин или личный кабинет учебного центра, может предложить вход без пароля по отпечатку пальца или PIN-коду. Ниже разберём на примерах, как добавить passkey к существующей системе с паролями.

Как устроен процесс WebAuthn

WebAuthn работает между тремя участниками: вашим сервером (в стандарте он называется relying party), браузером пользователя и аутентификатором, то есть телефоном, ноутбуком или USB-ключом безопасности. Процесс состоит из двух этапов. При регистрации сервер создаёт случайный challenge, браузер просит у аутентификатора новую пару ключей и возвращает открытый ключ на сервер. При входе сервер снова выдаёт новый challenge, аутентификатор подписывает его закрытым ключом, а сервер проверяет подпись сохранённым открытым ключом. Закрытый ключ никогда не покидает устройство, а сам ключ привязан к домену (rp ID), поэтому фишинговый сайт им воспользоваться не сможет.

Требования перед началом

На хостинге 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 обычно значит, что пользователь закрыл окно, это не проблема безопасности.

Похожие статьи

🛡️ Защита сайта на DLE: лицензия, админ-панель и папка uploads 🖱️ Clickjacking: защита сайта с помощью X-Frame-Options и CSP 🧩 Устаревший плагин: самая частая причина взлома сайта 🚪 Есть ли польза от смены порта SSH: мифы и реальность
🌐 Язык
🇺🇿 O'zbek 🇺🇿 Ўзбек 🇷🇺 Русский ✓ 🇬🇧 English