Технологічна галузь

Passkeys та WebAuthn у 2026: Практичний посібник з реалізації для веб-розробників

Passkeys and WebAuthn in 2026: A Practical Implementation Guide for Web Developers

Passkeys обіцяють безпарольний вхід без зберігання паролів, але правильна реалізація WebAuthn потребує більше, ніж просто виклик API браузера. Дізнайтеся, як реєстрація, автентифікація, перевірка на сервері, відкриті облікові дані та відновлення облікового запису працюють разом у безпечному веб-застосунку.

Passkeys та WebAuthn у 2026 році: Практичний посібник з реалізації для веб-розробників

Паролі десятиліттями були механізмом автентифікації за замовчуванням для веб-додатків. Вони також є постійним джерелом проблем з безпекою.

Користувачі повторно використовують їх. Зловмисники крадуть їх через фішинг. Сервери повинні захищати хеші паролів, керувати їх скиданням та захищатися від атак credential stuffing (перебору облікових даних).

Passkeys пропонують принципово інший підхід.

Замість прохання користувачам запам'ятовувати спільний секрет, passkeys використовують публічну ключову криптографію та автентифікатор, яким контролює користувач. Браузер надає стандартний інтерфейс через WebAuthn, тоді як сервер перевіряє криптографічні докази того, що використано правильний обліковий дані.

Технологія більше не є експериментальною. WebAuthn широко доступний у сучасних браузерах, а його JSON-методи зручності значно спростили інтеграцію.

Але побудова безпечного входу за допомогою passkey все ще вимагає ретельного бекенд-дизайну.

Цей посібник пояснює архітектуру, демонструє браузерні потоки та визначає перевірки на стороні сервера, які розробники не можуть ігнорувати.

1. Що саме таке passkey?

Passkey — це відкритий FIDO-обліковий дані, що використовується для автентифікації користувача через публічну ключову криптографію.

Під час реєстрації автентифікатор створює криптографічну пару ключів.

Приватний ключ залишається захищеним автентифікатором або його екосистемою управління обліковими даними. Веб-сайт отримує відповідний публічний клюв та пов'язує його з обліковим записом користувача.

Під час автентифікації сервер видає свіжий виклик (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" запитує відкритий обліковий дані (discoverable credential), що є необхідним для досвіду passkey.

userVerification: "required" запитує локальну верифікацію користувача, таку як ПІН пристрою або біометричну автентифікацію. Бекенд пізніше має перевірити, що верифікація дійсно відбулася.

Посібник Google з серверної реєстрації описує ці поля та рекомендує використовувати підтримувану бібліотеку WebAuthn для генерації та валідації даних реєстрації.

5. Створення passkey в JavaScript

Сучасні браузери надають корисний метод:

PublicKeyCredential.parseCreationOptionsFromJSON()

Він перетворює JSON-представлення, що містить base64url-закодовані двійкові поля, у структуру, очікувану WebAuthn.

Це уникає написання власної логіки конвертації base64url-to-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-сумісне представлення поверненого облікового дані, уникаючи ще одного рівня ручної двійкової серіалізації.

Ці зручності доступні в поточних браузерах, хоча додатки, що підтримують старіші версії браузерів, повинні забезпечувати обробку сумісності.

Код вище — лише браузерна сторона. Це не повна реалізація автентифікації.

6. Що сервер має перевірити під час реєстрації

Коли браузер повертає нові облікові дані, бекенд має їх перевірити перед збереженням чого-небудь.

Мінімально процес перевірки має встановити, що:

  1. Повернений виклик відповідає згенрованому для цієї спроби реєстрації.
  2. Виклик є свіжим і ще не був спожитий.
  3. Повідомлений origin відповідає явно довіреному origin додатку.
  4. Дані автентифікатора відповідають очікуваному RP ID.
  5. Виконано необхідні умови присутності користувача (user presence) та верифікації користувача (user verification).
  6. Публічний ключ та ідентифікатор облікового дані можуть бути витягнуті та перевірені.
  7. Реєстрація пов'язана з правильним автентифікованим обліковим записом.

Залежно від політики додатку, додаткові перевірки можуть включати підтримувані алгоритми, унікальність облікових даних та вимоги до атестації.

Успішна реєстрація типово зберігає:

Поле Призначення
credential_id Ідентифікує обліковий дані
user_id Пов'язує його з обліковим записом
public_key Перевіряє майбутні підписи
sign_count Відстежує дані лічильника автентифікатора
transports Опціональні підказки транспорту автентифікатора
created_at Часова мітка реєстрації
last_used_at Управління обліковим записом та аудит
backup_eligible / backup_state Опціональні метадані, пов'язані з резервним копіюванням

Точне представлення бази даних залежить від бібліотеки верифікації та додатку.

Не реалізуйте парсинг CBOR, верифікацію атестації чи криптографічну валідацію підписів з нуля, якщо у вас немає переконливого powodu та експертизи для його підтримки.

Специфікація 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) за збереженим публічним ключем, підтвердити виклик та origin, та примусити свою політику верифікації користувача.

Лише тоді він має встановити сеанс користувача.

parseRequestOptionsFromJSON() є частиною сучасного API WebAuthn і усуває необхідність вручну декодувати двійкові поля в поширених браузерних інтеграціях.

8. Додавання passkeys до існуючих форм входу з умовною медіацією

Одна з найкорисніших функцій WebAuthn — умовна медіація (conditional mediation), іноді називаема passkey autofill.

Замість показу окремого діалогу passkey одразу, браузер може пропонувати доступний passkey поруч з іншими збереженими обліковими даними, коли користувач взаємодіє з полем входу.

HTML input може використовувати:

<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. Чому перевірки виклику та origin є суттєвими

Passkeys стійкі до фішингу, але це не означає, що додаток може ігнорувати свій протокол автентифікації.

Виклик (challenge) захищає від атак повторного відтворення (replay attacks).

Без свіжого, непередбачуваного виклику зловмисник може спробувати повторно використати дані автентифікації з попереднього сеансу.

Перевірки origin та RP ID гарантують, що облікові дані використовуються в контексті призначеного веб-сайту.

Наприклад, passkey, створений для example.com, не може бути просто повторно використаний фішинговим сайтом-копіювалом, таким як examp1e.com.

Браузер та автентифікатор втілюють важливі частини цієї прив'язки до домену, тоді як бекенд незалежно перевіряє результаючі докази.

Хороша реалізація використовує короткоживучі виклики, споживає кожен виклик один раз і ніколи не приймає довільні origin лише тому, що вони мають знайомий вигляд імені хоста.

MDN рекомендує генерувати виклики в довіреному середовищі та інвалідувати їх після короткого періоду, зазвичай не більше приблизно десяти хвилин.

10. Не плутайте лічильники підписів

WebAuthn-автентифікатори можуть включати лічильник підписів.

Історично лічильники допомагали виявляти потенційно клоновані автентифікатори. Якщо лічильник несподівано перестає збільшуватися, relying party може розглянути це як сигнал ризику.

Однак не кожен автентифікатор підтримує значущий лічильник.

Деякі облікові дані завжди повідомляють нуль. Синхронізовані облікові дані також можуть ускладнювати інтерпретацію лічильника, оскільки кілька пристроїв можуть використовувати копії одного й того ж облікового дані.

Специфікація 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 IDs та довірені origin явно сконфігуровані.
  • Виклики є криптографічно випадковими, короткоживучими та одноразовими.
  • Реєстрація вимагає відповідної авторизації облікового запису.
  • Серверна верифікація слідує специфікації WebAuthn.
  • Публічні ключі та ідентифікатори облікових даних зберігаються безпечно.
  • Вхід встановлює сеанс лише після успішної верифікації.
  • Вимоги до верифікації користувача примушуються на сервері.
  • Видалення облікових даних та відновлення облікового запису захищені.
  • Декілька облікових даних на обліковий запис підтримуються там, де це доречно.
  • Помилки автентифікації та чутливі зміни облікового запису моніторяться.
  • Сценарії для мобільних, десктопних, крос-пристрійових та апаратних ключів протестовані.

Ці перевірки важливіші за те, чи може фронтенд відобразити привабливий біометричний запит входу.

Висновок: passkeys — це архітектура автентифікації, а не просто браузерна функція

WebAuthn робить автентифікацію публічного ключа доступною для звичайних веб-додатків.

Сучасні браузерні API усунули більшу частину роботи з серіалізацією, яка раніше ускладнювала інтеграцію passkey.

Але браузер — це лише одна частина системи.

Справжня робота з реалізацією полягає в управлінні викликами, серверній верифікації, зберіганні облікових даних, конфігурації домену, відновленні облікового запису та безпечних користувацьких подорожах.

Для розробників, що створюють сучасні додатки на PHP, JavaScript, Python або інших бекенд-середовищах, passkeys все частіше стають практичною альтернативою традиційним паролям.

Найкращою початковою точкою не є заміна цілої системи автентифікації за одну ніч.

Це реалізація одного повного, коректно перевіреного потоку реєстрації та входу, а потім побудова безпечної стратегії міграції навколо нього.