Passkeys и WebAuthn в 2026: Практическое руководство по реализации для веб-разработчиков
Passkeys обещают вход без пароля без хранения секретов пароля, но правильная реализация WebAuthn требует больше, чем просто вызов API браузера. Узнайте, как регистрация, аутентификация, проверка на стороне сервера, обнаруживаемые учетные данные и восстановление аккаунта сочетаются в безопасном веб-приложении.
Passkeys и WebAuthn в 2026 году: Практическое руководство по реализации для веб-разработчиков
Пароли десятилетиями оставались механизмом аутентификации по умолчанию для веб-приложений. Они также являются постоянным источником проблем безопасности.
Пользователи повторно используют их. Злоумышленники крадут их через фишинг. Серверы должны защищать хеши паролей, управлять сбросами и защищаться от атак подбора учетных данных (credential stuffing).
Passkeys предлагают принципиально иной подход.
Вместо того чтобы просить пользователей запоминать общий секрет, passkeys используют криптографию с открытым ключом и аутентификатор, контролируемый пользователем. Браузер предоставляет стандартный интерфейс через WebAuthn, а сервер проверяет криптографическое доказательство того, что использовались верные учетные данные.
Технология больше не является экспериментальной. WebAuthn широко доступен в современных браузерах, а его JSON-методы удобства значительно упростили интеграцию.
Но создание безопасного входа через passkey все еще требует тщательного проектирования бэкенда.
Это руководство объясняет архитектуру, демонстрирует потоки на стороне браузера и выделяет проверки на стороне сервера, которые разработчики не должны упускать.
1. Что такое passkey?
Passkey — это обнаруживаемый (discoverable) FIDO-credential, используемый для аутентификации пользователя через криптографию с открытым ключом.
Во время регистрации аутентификатор создает криптографическую пару ключей.
Закрытый ключ остается защищенным аутентификатором или его экосистемой управления учетными данными. Веб-сайт получает соответствующий открытый ключ и связывает его с учетной записью пользователя.
Во время аутентификации сервер выдает свежий вызов (challenge). Аутентификатор подписывает данные, связанные с этим вызовом, а сервер проверяет подпись, используя сохраненный открытый ключ.
На веб-сайт не отправляется повторно используемый пароль.
Аутентификатором может быть смартфон, компьютер с Windows Hello, аппаратный ключ безопасности или менеджер учетных данных, поддерживающий синхронизируемые passkeys.
Не каждый passkey синхронизируется между устройствами. Некоторые учетные данные остаются привязанными к устройству, в то время как другие могут быть безопасно сохранены в резервной копии и сделаны доступными через провайдера учетных данных.
Спецификации FIDO разработаны для сопротивления фишингу за счет привязки учетных данных к домену relying party. Биометрические данные, когда они используются, обрабатываются локально устройством, а не отправляются на веб-сайт.
2. WebAuthn — это браузерный API за passkeys
WebAuthn — это API веб-платформы, который позволяет веб-сайтам создавать и использовать учетные данные с открытым ключом.
Два браузерных метода образуют основу:
navigator.credentials.create()
navigator.credentials.get()
Первый создает учетные данные. Второй запрашивает аутентификацию с использованием существующих учетных данных.
Оба метода работают с опцией publicKey и требуют безопасного контекста, обычно HTTPS.
Важно: браузер не решает, аутентифицирован ли пользователь. Он возвращает данные, которые бэкенд должен проверить.
Успешный браузерный запрос не является доказательством того, что вход следует принять.
Сервер остается ответственным за проверку вызова (challenge), источника (origin), идентификатора relying party и криптографического доказательства.
3. Понимание полной архитектуры
Типичная реализация содержит четыре компонента:
- Фронтенд веб-приложения, который вызывает WebAuthn.
- Бэкенд приложения, который генерирует вызовы и проверяет ответы.
- Аутентификатор или провайдер passkey, который защищает закрытый ключ.
- База данных, которая хранит метаданные учетных данных и открытые ключи.
Поток регистрации: веб-приложение запрашивает опции регистрации; бэкенд генерирует вызов и данные пользователя; браузер и аутентификатор создают учетные данные и пару ключей; бэкенд проверяет результат и сохраняет открытый ключ.
Сервер никогда не должен доверять данным регистрации только потому, что они были возвращены браузером.
Злоумышленный клиент может отправить произвольные HTTP-запросы, не используя ожидаемый фронтенд вообще.
Именно поэтому проверка должна происходить на сервере.
4. Генерация опций регистрации на сервере
Перед вызовом WebAuthn бэкенд генерирует вызов регистрации и опции.
Представительный объект опций выглядит так:
{
"rp": {
"name": "Example Application",
"id": "example.com"
},
"user": {
"id": "dXNlci0xMjM",
"name": "alex@example.com",
"displayName": "Alex"
},
"challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"authenticatorSelection": {
"residentKey": "required",
"userVerification": "required"
},
"attestation": "none",
"timeout": 300000
}
Это иллюстративный JSON, не полный производственный ответ.
Несколько полей важны.
rp.id идентифицирует relying party. Например, example.com может использоваться для соответствующих поддоменов этого домена, в соответствии с правилами валидации RP ID WebAuthn.
user.id должен быть стабильным, непрозрачным идентификатором аккаунта, закодированным как base64url для JSON-транспорта. Он не должен раскрывать лишнюю личную информацию.
challenge должен генерироваться с использованием криптографически безопасного случайного источника на сервере.
residentKey: "required" запрашивает обнаруживаемые учетные данные, что необходимо для взаимодействия с passkey.
userVerification: "required" запрашивает локальную верификацию пользователя, такую как PIN устройства или биометрическая аутентификация. Бэкенд позже должен проверить, что верификация действительно произошла.
Руководство Google по серверной регистрации описывает эти поля и рекомендует использовать поддерживаемую WebAuthn-библиотеку для генерации и валидации данных регистрации.
5. Создание passkey в JavaScript
Современные браузеры предоставляют полезный метод:
PublicKeyCredential.parseCreationOptionsFromJSON()
Он преобразует JSON-представление, содержащее бинарные поля, закодированные в base64url, в структуру, ожидаемую WebAuthn.
Это позволяет избежать написания пользовательской логики конвертации base64url в ArrayBuffer для каждого поля.
Вот упрощенная браузерная функция регистрации:
async function registerPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/register/options',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
}
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start registration');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseCreationOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.create({
publicKey
});
if (!credential) {
throw new Error('No credential was created');
}
const verifyResponse = await fetch(
'/api/passkeys/register/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Registration verification failed');
}
return await verifyResponse.json();
}
Переменная csrfToken представляет токен против CSRF, предоставляемый приложением. Сервер должен его проверить. Пример также предполагает, что страница уже связана с безопасно аутентифицированным пользователем.
credential.toJSON() предоставляет JSON-friendly представление возвращенных учетных данных, избегая еще одного уровня ручной бинарной сериализации.
Эти удобства доступны в текущих браузерах, хотя приложения, поддерживающие старые версии браузеров, должны обеспечивать обработку совместимости.
Приведенный выше код — это только браузерная сторона. Это не полная реализация аутентификации.
6. Что сервер должен проверить при регистрации
Когда браузер возвращает новые учетные данные, бэкенд должен их проверить перед сохранением.
Как минимум, процесс проверки должен установить, что:
- Возвращенный вызов соответствует сгенерированному для этой попытки регистрации.
- Вызов свежий и еще не был использован.
- Сообщенный источник (origin) соответствует явно доверенному источнику приложения.
- Данные аутентификатора соответствуют ожидаемому RP ID.
- Выполнены требуемые условия присутствия пользователя (user presence) и верификации пользователя (user verification).
- Открытый ключ и идентификатор учетных данных могут быть извлечены и проверены.
- Регистрация связана с правильной аутентифицированной учетной записью.
В зависимости от политики приложения, дополнительные проверки могут включать поддерживаемые алгоритмы, уникальность учетных данных и требования к аттестации.
Успешная регистрация обычно сохраняет:
| Поле | Назначение |
|---|---|
credential_id |
Идентифицирует учетные данные |
user_id |
Связывает их с аккаунтом |
public_key |
Проверяет будущие подписи |
sign_count |
Отслеживает данные счетчика аутентификатора |
transports |
Опциональные подсказки транспорта аутентификатора |
created_at |
Временная метка регистрации |
last_used_at |
Управление аккаунтом и аудит |
backup_eligible / backup_state |
Опциональные метаданные, связанные с резервным копированием |
Точное представление в базе данных зависит от библиотеки верификации и приложения.
Не реализовывайте парсинг CBOR, верификацию аттестации или криптографическую проверку подписей с нуля, если у вас нет веской причины и экспертизы для их поддержки.
Спецификация W3C определяет подробные процедуры верификации регистрации и аутентификации.
7. Аутентификация существующего пользователя
Аутентификация следует похожей структуре, но не создает новую пару ключей.
Сервер генерирует новый вызов и отправляет опции аутентификации в браузер.
Для входа через обнаруживаемый passkey эти опции могут содержать:
{
"challenge": "NEW_SERVER_GENERATED_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"timeout": 300000
}
Затем браузер может запросить учетные данные:
async function authenticateWithPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/login/options',
{
credentials: 'same-origin'
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start authentication');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseRequestOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.get({
publicKey
});
if (!credential) {
throw new Error('Authentication was cancelled');
}
const verifyResponse = await fetch(
'/api/passkeys/login/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Authentication failed');
}
return await verifyResponse.json();
}
Этот пример предполагает, что бэкенд связывает выпущенный вызов с кратковременной анонимной транзакцией входа, применяет соответствующее ограничение скорости (rate limiting) и устанавливает новый аутентифицированный сеанс только после успешной проверки.
Сервер должен найти учетные данные по ID, проверить подписанное утверждение (assertion) с сохраненным открытым ключом, подтвердить вызов и источник, и применить свою политику верификации пользователя.
Только после этого он должен установить сеанс пользователя.
parseRequestOptionsFromJSON() является частью современного WebAuthn API и устраняет необходимость вручную декодировать бинарные поля в распространенных браузерных интеграциях.
8. Добавление passkeys в существующие формы входа с условной медиацией
Одна из самых полезных функций WebAuthn — условная медиация (conditional mediation), иногда называемая автозаполнением passkey.
Вместо того чтобы сразу показывать отдельный диалог passkey, браузер может предложить доступный passkey наряду с другими сохраненными учетными данными, когда пользователь взаимодействует с полем входа.
HTML-инпут может использовать:
<input
type="text"
name="username"
autocomplete="username webauthn"
>
Приложение может проверить поддержку:
const supported =
await PublicKeyCredential.isConditionalMediationAvailable();
if (supported) {
// Request authentication with mediation: 'conditional'.
}
При вызове navigator.credentials.get() приложение использует:
{
publicKey,
mediation: 'conditional'
}
Для автозаполнения обнаруживаемых учетных данных опции сервера не должны ограничивать запрос конкретным списком ID учетных данных.
Условная медиация особенно полезна при постепенной миграции от паролей, потому что пользователям не нужно помнить, есть ли у конкретного аккаунта passkey.
Браузер может представить подходящие варианты в привычном опыте входа.
9. Почему проверки вызова (challenge) и источника (origin) критически важны
Passkeys устойчивы к фишингу, но это не означает, что приложение может игнорировать свой протокол аутентификации.
Вызов защищает от атак повторного воспроизведения (replay attacks).
Без свежего, непредсказуемого вызова злоумышленник может попытаться повторно использовать данные аутентификации из предыдущего сеанса.
Проверки источника и RP ID гарантируют, что учетные данные используются в контексте предполагаемого веб-сайта.
Например, passkey, созданный для example.com, не может быть просто повторно использован похожим фишинговым сайтом, таким как examp1e.com.
Браузер и аутентификатор обеспечивают важные части этой привязки к домену, в то время как бэкенд независимо проверяет полученные доказательства.
Хорошая реализация использует кратковременные вызовы, потребляет каждый вызов один раз и никогда не принимает произвольные источники только потому, что они имеют знакомый hostname.
MDN рекомендует генерировать вызовы в доверенной среде и аннулировать их после короткого периода, обычно не более примерно десяти минут.
10. Не неверно трактуйте счетчики подписей
WebAuthn-аутентификаторы могут включать счетчик подписей (signature counter).
Исторически счетчики помогали обнаруживать потенциально клонированные аутентификаторы. Если счетчик неожиданно перестает увеличиваться, relying party может рассматривать это как сигнал риска.
Однако не каждый аутентификатор поддерживает значимый счетчик.
Некоторые учетные данные всегда сообщают ноль. Синхронизируемые учетные данные также могут усложнить интерпретацию счетчика, потому что несколько устройств могут использовать копии одного и того же credential.
Спецификация W3C явно рассматривает неожиданное поведение счетчика как возможный сигнал, а не окончательное доказательство клонирования.
Поэтому разработчики не должны слепо отклонять каждый вход, счетчик которого равен нулю или не изменился.
Используйте счетчик в соответствии с поведением аутентификатора, руководством библиотеки верификации WebAuthn и политикой безопасности приложения.
11. Восстановление аккаунта — часть безопасности passkey
Реализация passkey неполна без стратегии восстановления.
Что происходит, когда пользователь теряет устройство?
Что если они удаляют свой единственный passkey?
Что если они меняют провайдеров учетных данных или не могут получить доступ к синхронизированным учетным данным?
Разумный дизайн позволяет пользователям регистрировать несколько passkeys и управлять ими из настроек аккаунта.
Интерфейс управления должен отображать узнаваемые имена учетных данных, даты создания и информацию о недавнем использовании, где доступно.
Пользователи должны иметь возможность отозвать учетные данные, которым они больше не доверяют.
Но механизм восстановления заслуживает особого внимания.
Если злоумышленник может обойти аутентификацию passkey, используя слабый процесс восстановления по email, общий аккаунт так же безопасен, как этот путь восстановления.
Для аккаунтов с более высоким риском рассмотрите более строгую верификацию восстановления, коды восстановления, дополнительные зарегистрированные аутентификаторы и уведомления о конфиденциальных изменениях аккаунта.
Руководство Google по UX passkey рекомендует установить метод восстановления и поддерживать несколько passkeys там, где это уместно.
12. Распространенные ошибки реализации
Несколько ошибок регулярно подрывают иначе перспективные интеграции passkey.
Обработка успеха браузера как серверной аутентификации. Разрешенное промиса navigator.credentials.get() не заменяет серверную криптографическую верификацию.
Генерация вызовов в JavaScript. Вызовы должны приходить от доверенного сервера и быть привязаны к соответствующей транзакции аутентификации.
Использование неверного RP ID. Область действия домена — это функция безопасности, а не косметическая настройка. Продакшн, стейджинг и локальные среды разработки требуют намеренной конфигурации.
Предположение, что все passkeys синхронизируются. Привязанные к устройству учетные данные остаются важной частью экосистемы.
Забывание об отзыве учетных данных. Пользователям нужен способ удалить потерянный или скомпрометированный аутентификатор из своего аккаунта.
Создание слабого запасного варианта. Фишингоустойчивый вход теряет большую часть своей ценности, если восстановление аккаунта может быть легко эксплуатировано.
Игнорирование старых браузеров. Современные JSON-методы удобства снижают сложность, но приложения с требованиями к старым браузерам все еще могут нуждаться в коде совместимости.
Пропуск защиты от CSRF и сессий. Регистрация и операции управления учетными данными — это конфиденциальные изменения аккаунта. Им нужны те же защиты, что и другим высокоэффективным действиям с аккаунтом.
Написание пользовательской криптографической верификации без необходимости. Поддерживаемая серверная библиотека WebAuthn обычно безопаснее, чем реализация спецификации напрямую.
13. Должен ли каждый веб-сайт немедленно заменить пароли?
Не обязательно.
Passkeys могут улучшить как удобство использования, так и безопасность, но стратегия миграции имеет значение.
Для нового приложения безпарольная регистрация может быть разумным значением по умолчанию, если продукт имеет хорошо спроектированный поток восстановления и поддерживает свои целевые платформы.
Для существующего приложения с тысячами пользователей постепенное внедрение часто безопаснее.
Начните с того, чтобы разрешить аутентифицированным пользователям регистрировать passkeys в настройках аккаунта.
Затем добавьте вход через passkey наряду с существующей системой аутентификации.
Внедрите условную медиацию там, где она поддерживается.
Измеряйте успешность регистрации, ошибки аутентификации, совместимость устройств и запросы восстановления.
Наконец, рассмотрите возможность сделать passkeys предпочтительным методом аутентификации, когда пользовательский опыт и механизмы восстановления станут достаточно зрелыми.
Поэтапный выпуск также упрощает выявление браузерных проблем без блокировки легальных пользователей.
14. Чек-лист готовности к продакшну
Перед включением passkeys в продакшн проверьте следующее:
- Все операции WebAuthn выполняются в соответствующем безопасном контексте.
- RP ID и доверенные источники явно настроены.
- Вызовы криптографически случайны, кратковременны и одноразовы.
- Регистрация требует соответствующей авторизации аккаунта.
- Серверная верификация следует спецификации WebAuthn.
- Открытые ключи и идентификаторы учетных данных хранятся безопасно.
- Вход устанавливает сеанс только после успешной верификации.
- Требования верификации пользователя применяются на сервере.
- Удаление учетных данных и восстановление аккаунта защищены.
- Поддержка нескольких учетных данных на аккаунт реализована там, где уместно.
- Ошибки аутентификации и конфиденциальные изменения аккаунта мониторятся.
- Сценарии мобильных, десктопных, кросс-девайс и аппаратных ключей протестированы.
Эти проверки важнее того, может ли фронтенд отображать привлекательный биометрический запрос входа.
Заключение: passkeys — это архитектура аутентификации, а не просто браузерная функция
WebAuthn делает аутентификацию с открытым ключом доступной для обычных веб-приложений.
Современные браузерные API устранили большую часть работы по сериализации, которая ранее делала интеграцию passkey громоздкой.
Но браузер — это только одна часть системы.
Настоящая работа по реализации заключается в управлении вызовами, серверной верификации, хранении учетных данных, конфигурации домена, восстановлении аккаунта и безопасных пользовательских путях.
Для разработчиков, создающих современные приложения на PHP, JavaScript, Python или других бэкенд-средах, passkeys все чаще стоит рассматривать как практичную альтернативу традиционным паролям.
Лучшая отправная точка — не заменять всю систему аутентификации за одну ночь.
Это — реализовать один полный, правильно верифицированный поток регистрации и входа, а затем построить вокруг него безопасную стратегию миграции.