Немедленная медиация WebAuthn: подробный разбор

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

Переход на passkeys создает «парадокс passkeys»: у некоторых пользователей уже есть passkeys, в то время как многие по-прежнему используют традиционные пароли. Это приводит к загромождению экранов входа множеством кнопок: «Войти с паролем», «Войти через Google» и «Войти с помощью passkey». Такая фрагментация создает неудобства. Пользователь может нажать «Войти с помощью passkey» на новом устройстве и столкнуться с непонятным запросом QR-кода, потому что его passkey недоступен локально. Основная проблема заключается в том, что сайт не может узнать контекст пользователя до начала процесса аутентификации.

Одно из решений — это подход с идентификатором в первую очередь, который определяет лучший метод входа для пользователя. Другое потенциальное решение — единая интеллектуальная кнопка «Войти», которая организует наиболее плавный процесс для каждого пользователя. Она должна напрямую запрашивать passkey, если он доступен на устройстве, или плавно переключаться на другие методы, если нет.

Была анонсирована новая функция WebAuthn, которая может сделать это возможным: немедленная медиация (mediation: 'immediate'). Устанавливая это свойство в вызове WebAuthn API, разработчики могут создать интеллектуальный, унифицированный опыт входа, который решает парадокс passkeys. В этой статье мы проведем ориентированный на разработчиков анализ mediation: 'immediate', исследуя, что это такое, как это работает и как это реализовать.

Чтобы понять немедленную медиацию, полезно сначала узнать о других вариантах. Медиация пользователя в WebAuthn — это то, как браузер управляет взаимодействием между вашим сайтом (доверяющей стороной) и аутентификатором пользователя (например, Face ID, YubiKey).

Это классический, явный процесс WebAuthn. Когда доверяющая сторона вызывает navigator.credentials.get(), не указывая предпочтения mediation, браузер всегда показывает модальное диалоговое окно. Это окно перекрывает содержимое страницы, требуя немедленного внимания пользователя и приостанавливая любое другое взаимодействие с сайтом.

• Сценарий использования: Лучше всего подходит для отдельных кнопок «Войти с помощью passkey», когда пользователь четко выразил свое намерение.
• Ограничение: Если у пользователя нет passkey на текущем устройстве, ему показывают процесс для другого устройства (например, QR-код), что может сбить с толку и завести в тупик.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

Этот режим, введенный для помощи пользователям в переходе на passkeys, является более тонким. При mediation: 'conditional' запрос WebAuthn привязывается к полю ввода (например, имени пользователя) с атрибутом autocomplete="webauthn". Когда пользователь нажимает на поле, интерфейс автозаполнения браузера предлагает все доступные passkeys.

• Сценарий использования: Идеально подходит для постепенного улучшения традиционных форм входа, позволяя пользователям обнаруживать и использовать passkeys без отдельной кнопки.
• Ограничение: Этот режим настолько строго отдает приоритет конфиденциальности, что если у пользователя нет passkey или он не взаимодействует с запросом, промис вызова API никогда не разрешается. Сайт не получает никакого сигнала, что делает невозможным организацию резервного интерфейса.

mediation: 'immediate' — это решение проблемы «единой кнопки входа». Она предоставляет сайту надежный способ проверить наличие passkey перед отображением какого-либо интерфейса.

Вместо того чтобы приказывать пользователю аутентифицироваться с помощью passkey через модальное окно, немедленная медиация спрашивает браузер: «Есть ли готовый к использованию passkey для этого пользователя на этом устройстве прямо сейчас?»

Важно отметить, что этот запрос проверяет только локально доступные учетные данные (например, встроенные в устройство аутентификаторы, такие как Windows Hello, или passkeys, синхронизированные через менеджер паролей). Он разработан так, чтобы избегать запуска процесса с QR-кодом для другого устройства, который является частым источником проблем.

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

Сила этой функции заключается в ее четком, бинарном результате. Промис, возвращаемый navigator.credentials.get(), либо выполнится успешно, либо завершится с ошибкой, давая разработчику ясный сигнал.

• Путь 1 (Успех): Учетные данные существуют. Если браузер находит локально доступный passkey, он обходит интерфейс сайта и немедленно представляет собственное нативное модальное окно, например, для выбора учетной записи. Если пользователь успешно аутентифицируется, промис разрешается с объектом PublicKeyCredential.
• Путь 2 (Неудача): Учетные данные отсутствуют. Если браузер не находит локально доступных учетных данных, он не показывает никакого интерфейса. Вместо этого промис navigator.credentials.get() немедленно отклоняется с DOMException под названием NotAllowedError.

NotAllowedError — это не ошибка, а скорее особенность. Это надежный, мгновенный сигнал о том, что сайту следует перейти к резервному методу аутентификации. Это позволяет разработчикам использовать простой блок try...catch: блок try пытается выполнить плавный процесс с passkey, а блок catch отлавливает NotAllowedError, чтобы отобразить традиционную форму входа. Это элегантно решает проблему единой кнопки входа, создавая одну точку входа, которая интеллектуально адаптируется к контексту пользователя.

Выбор правильного режима медиации — это критически важное решение для UX. В этой таблице представлено их сравнение.

Вот практическое пошаговое руководство по реализации mediation: 'immediate'.

Поскольку mediation: 'immediate' — это новая функция, надежное определение ее поддержки имеет решающее значение.

// Feature detection is essential for progressive enhancement.
let immediateMediationAvailable = false;
 
if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
    try {
        const capabilities = await PublicKeyCredential.getClientCapabilities();
        // The 'immediateGet' capability signals browser support.
        immediateMediationAvailable = capabilities.immediateGet === true;
    } catch (e) {
        console.error("Error getting client capabilities:", e);
    }
}

Этот вызов должен быть инициирован действием пользователя, например, кликом по кнопке.

// This function should be the event handler for your primary "Sign In" button.
async function handleSignInClick() {
    if (!immediateMediationAvailable) {
        // Fall back to showing a legacy login form if the feature isn't supported.
        showLegacyLoginForm();
        return;
    }
 
    try {
        // Fetch a fresh, random challenge from your server for each attempt.
        const challenge = await fetchChallengeFromServer();
 
        const publicKeyCredentialRequestOptions = {
            challenge: challenge, // The server-provided challenge as a Uint8Array
            rpId: "example.com",
            // The allowCredentials list MUST be empty for immediate mediation
            // to protect user privacy.
            allowCredentials: [],
        };
 
        const credential = await navigator.credentials.get({
            publicKey: publicKeyCredentialRequestOptions,
            // This is the key that enables the immediate mediation flow.
            mediation: "immediate",
        });
 
        // If the promise resolves, send the credential to your server for verification.
        await verifyCredentialOnServer(credential);
    } catch (error) {
        // The catch block is a critical part of the control flow.
        handleAuthError(error);
    }
}

Блок catch — это место, где реализуется «интеллект» единой кнопки входа.

// Handling the NotAllowedError is the key to the fallback mechanism.
function handleAuthError(error) {
    // Check the 'name' property of the DOMException.
    if (error.name === "NotAllowedError") {
        // This is the expected signal to show the traditional login form.
        console.log("No local passkey found. Showing legacy login form.");
        showLegacyLoginForm();
    } else {
        // This handles other potential errors, like the user dismissing the prompt.
        console.error("Authentication error:", error);
    }
}

Для наиболее плавного опыта вы можете попросить браузер искать как passkeys, так и сохраненные пароли в одном запросе, добавив password: true.

// Combining passkeys and passwords for a truly unified sign-in experience.
const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    password: true, // Ask the browser to include saved passwords.
    mediation: "immediate",
});
 
// The returned 'credential' object will either be a PublicKeyCredential
// or a PasswordCredential. Your server-side logic must handle both.

1. Одновременные запросы WebAuthn: Ожидающий conditional запрос (часто запускаемый при загрузке страницы) может заблокировать новый immediate запрос. Рассмотрите возможность использования AbortController для отмены любых ожидающих запросов перед запуском нового.
2. Ограничение на allowCredentials: Массив allowCredentials должен быть пустым. Предоставление идентификаторов учетных данных приведет к сбою вызова. Это важная мера защиты конфиденциальности, чтобы предотвратить проверку сайтами наличия конкретных, известных пользователей.
3. Требование действия пользователя: Вызов должен быть инициирован действием пользователя (например, событием 'click'). Вызов его программно при загрузке страницы будет заблокирован браузерами в качестве меры защиты конфиденциальности.

mediation: 'immediate' была разработана с четким пониманием компромиссов в области безопасности и конфиденциальности.

Основной компромисс — это «утечка одного бита». Отслеживая время разрешения промиса, доверяющая сторона может сделать вывод об одном бите информации: был ли промис отклонен мгновенно (нет локального ключа) или была задержка (был показан UI, потому что найден локальный ключ). Цель этой утечки — обеспечить лучший UX.

Разработчики предвидели возможность злоупотреблений (например, отслеживание пользователей) и встроили несколько обязательных мер защиты:

1. Обязательное действие пользователя: Вызов API должен быть инициирован действием пользователя, таким как клик. Это не позволяет сайту незаметно проверять наличие учетных записей при загрузке страницы и делает масштабный фингерпринтинг непрактичным.
2. Отключено в приватном режиме/режиме инкогнито: Функция запрещена в режимах приватного просмотра, чтобы предотвратить связывание активности пользователя между обычными и приватными сессиями.
3. Запрет на использование списка allowCredentials: Массив allowCredentials должен быть пустым. Это не позволяет сайту использовать эту функцию для проверки, посещает ли его конкретный известный пользователь.
4. Только в контексте основного домена: Функция запрещена в сторонних контекстах (например, в iframe с другого домена), чтобы предотвратить межсайтовое отслеживание.

Эти меры гарантируют, что основные гарантии безопасности WebAuthn остаются неизменными. Сама церемония аутентификации не меняется и остается устойчивой к фишингу.

mediation: 'immediate' — это продвинутая функция из спецификации WebAuthn Level 3, и ее внедрение продолжается. По состоянию на середину 2025 года стратегия постепенного улучшения является необходимой.

Хотя mediation: 'immediate' предоставляет отличный низкоуровневый инструмент для создания более умной кнопки входа, важно отличать его от более широкого решения «Passkey Intelligence», такого как то, что предлагает Corbado. Оба нацелены на решение парадокса passkeys и увеличение их внедрения, но делают это по-разному.

Passkey Intelligence идет на шаг дальше, собирая и оценивая данные с течением времени. Это позволяет осуществлять более сложные и своевременные вмешательства. Например, бэкенд Passkey Intelligence может обнаружить:

• Пользователя, успешно аутентифицировавшегося с паролем на новом устройстве, поддерживающем passkeys, и предложить ему добавить passkey для следующего раза.
• Пользователя, завершившего «гибридный» вход с другого устройства, и немедленно предложить ему зарегистрировать новое устройство.
• Пользователя, которому не удалось войти на новом устройстве, и предложить создание passkey в качестве опции восстановления или настройки (автоматическое исправление).

Этот подход, основанный на данных, не зависит от поддержки браузером mediation: 'immediate', что означает, что он может обеспечить более интеллектуальный процесс входа для всех ваших пользователей прямо сейчас.

Лучшее из двух миров

В конечном счете, эти два подхода не являются взаимоисключающими; они дополняют друг друга. Идеальное решение сочетает их:

1. Используйте сервис Passkey Intelligence в качестве «мозга» вашего процесса входа.
2. Затем сервис может использовать mediation: 'immediate' в качестве одного из своих сигналов в поддерживаемых браузерах для выполнения быстрой первоначальной проверки.
3. На основе результата — или отсутствия поддержки функции — сервис аналитики может затем использовать свои более богатые исторические данные для организации идеального резервного варианта, будь то отображение поля для пароля или предложение своевременного запроса на создание passkey.

Сочетая нативную скорость mediation: 'immediate' с глубокими инсайтами бэкенда Passkey Intelligence, вы можете обеспечить максимально плавный, адаптивный и эффективный опыт входа, мягко направляя каждого пользователя к будущему без паролей.

Немедленная медиация — это отличное улучшение опыта входа. Она предоставляет интеллект, необходимый для устранения распространенных источников трения и путаницы для пользователей во время перехода на passkeys.

• Уменьшает путаницу у пользователей: Позволяя использовать единую кнопку «Войти», immediate медиация снимает когнитивную нагрузку с пользователя. Ему больше не нужно помнить, какой метод аутентификации он настроил, или выбирать из загроможденного списка опций. Процесс входа становится проще и интуитивнее.
• Предотвращает отказы от входа с passkey: Частая причина, по которой пользователи прерывают вход с помощью passkey, — это неожиданное появление QR-кода для входа с другого устройства. Поскольку mediation: 'immediate' ищет только локальные учетные данные, она полностью избегает этой запутанной ситуации. Вместо того чтобы пользователь прерывал процесс, приложение получает четкий сигнал (NotAllowedError) для плавного перехода к другому методу, что приводит к более гладкому пути.
• Создает плавный, интеллектуальный процесс: Основное преимущество — это умный опыт входа. Приложение может спросить у браузера, возможен ли плавный вход с помощью passkey, прежде чем отображать какой-либо UI. Этот подход «Спрашивай, а не приказывай» гарантирует, что пользователи видят только те запросы, которые для них актуальны. Это делает вход умным и адаптивным, подчеркивая удобство passkeys и поощряя их дальнейшее использование.

Немедленная медиация — это новая функция WebAuthn, которая решает проблему фрагментированного опыта входа в период перехода на passkeys. Она позволяет создать единую, интеллектуальную кнопку «Войти», которая адаптируется к контексту пользователя, устраняя путаницу и трение. Хотя она вводит просчитанный компромисс в отношении конфиденциальности, она включает надежные меры защиты для снижения рисков без ущерба для основной безопасности WebAuthn.

Для разработчиков путь вперед — это постепенное улучшение. Создайте надежный базовый опыт и добавляйте immediate медиацию поверх него для поддерживаемых браузеров. Внедрение этой функции — это стратегический шаг для ускорения внедрения passkeys, повышения безопасности, снижения операционных расходов и улучшения конверсии.

Реализация этих передовых потоков аутентификации может быть сложной. Платформа Enterprise Passkey от Corbado абстрагирует эту сложность. Наша инфраструктура управляет оптимальной оркестрацией потоков, включая условную и immediate медиацию, что позволяет вашей команде с уверенностью развернуть современный, бесшовный опыт аутентификации.