Возможности клиента WebAuthn

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

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

Стандарт WebAuthn Level 3 вводит новые возможности клиента (которые можно получить через API браузера getClientCapabilities()), призванные дать разработчикам и платформам больше контроля и гибкости при внедрении passkeys. Эти обновления упрощают процесс интеграции passkeys на разных устройствах, браузерах и платформах, обеспечивая более плавный и согласованный пользовательский путь.

В этой статье мы ответим на следующие вопросы:

1. Что такое возможности клиента WebAuthn?
2. Какие возможности клиента WebAuthn существуют?
3. Как возможности клиента WebAuthn улучшают реализацию passkeys?
4. Почему эти возможности важны как для разработчиков, так и для продакт-менеджеров?

К концу статьи мы разберемся, как эти функции помогают создавать бесшовные и безопасные процессы аутентификации, соответствующие современным ожиданиям пользователей.

Возможности клиента (client capabilities) WebAuthn — это набор функций, позволяющих браузерам и платформам сообщать, какие типы функциональности WebAuthn они поддерживают. Проще говоря, они действуют как «чек-лист функций», который дает сайтам понять, какие методы аутентификации и настройки доступны на устройстве пользователя. Это позволяет разработчикам адаптировать процессы входа в зависимости от возможностей клиента, обеспечивая более плавный и безопасный UX.

Например, если браузер сообщает, что поддерживает биометрическую аутентификацию (например, Touch ID), разработчики могут предложить пользователям вариант входа по отпечатку пальца. И наоборот, если браузер не поддерживает определенные функции, можно предоставить резервные варианты, такие как пароль или SMS OTP. На практике неподдерживаемые или прерванные сценарии все еще могут проявляться как общие ошибки браузера, поэтому командам стоит сопоставлять эти результаты с явной классификацией ошибок WebAuthn.

Стандарт WebAuthn Level 3 вводит несколько новых возможностей клиента, которые делают реализацию passkeys более универсальной и удобной. Первая поддержка вызова API getClientCapabilities() появилась в Safari 17.4.

Чтобы определить поддержку в браузере, будет полезен следующий фрагмент кода:

// Check if PublicKeyCredential is supported in the current browser
if (typeof PublicKeyCredential === "undefined") {
    console.log("PublicKeyCredential is not supported in this browser.");
}
 
// Check if getClientCapabilities method exists on PublicKeyCredential
if (typeof PublicKeyCredential.getClientCapabilities === "function") {
    try {
        let capabilities = await PublicKeyCredential.getClientCapabilities();
        console.log(capabilities);
    } catch (error) {
        console.error("Error getting client capabilities:", error);
    }
} else {
    console.log("getClientCapabilities is not supported in this browser");
}

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

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Давайте подробнее рассмотрим возможности клиента WebAuthn и то, как они влияют на интеграцию passkeys:

Возможность conditionalCreate позволяет автоматическое создание passkeys при определенных условиях. Приложение может использовать эту функцию для автоматического создания passkey во время автозаполнения паролей, если менеджер паролей имеет соответствующую поддержку. Эта функция помогает ускорить внедрение passkeys и их последующее использование, автоматически переводя пользователей с паролей на passkeys.

Подобно conditionalCreate, функция conditionalGet автоматически запускает вход по passkey. Это полезно в сценариях, где нужно включить наилучший UX, делая логин не только беспарольным, но и без ввода имени пользователя (пользователи просто кликают на выбранный passkey в модальном окне или выпадающем списке и могут аутентифицироваться). Используя эту возможность, мы можем гарантировать, что аутентификация по passkey происходит только тогда, когда это уместно, минимизируя лишние запросы и улучшая опыт пользователя.

Функция hybridTransport гарантирует, что passkeys можно использовать на разных устройствах, обеспечивая бесшовную кросс-девайс аутентификацию (через QR-коды и Bluetooth). Например, пользователь может использовать passkey, сохраненный на смартфоне, для входа в сервис на своем десктопе. Эта возможность позволяет пользователям безопасно аутентифицироваться без необходимости вручную переносить passkeys или полагаться на традиционные методы входа для каждого устройства, способствуя созданию единого опыта аутентификации.

Платформенные аутентификаторы, такие как Windows Hello, Face ID или Touch ID, встроены непосредственно в устройства и предлагают более быстрый, плавный и безопасный опыт работы с passkeys, позволяя пользователям аутентифицироваться с помощью биометрии или других нативных методов (например, PIN-кода).

Become part of our Passkeys Community for updates & support.

Join

Возможность userVerifyingPlatformAuthenticator гарантирует, что аутентификация по passkey включает проверку пользователя, такую как активное сканирование отпечатка пальца или распознавание лица, что обеспечивает дополнительный уровень безопасности.

Возможность relatedOrigins позволяет бесшовно аутентифицироваться в разных доменах, принадлежащих одной организации (например, amazon.com и amazon.de). Например, если компания управляет несколькими доменами или имеет разные поддомены, пользователи могут войти один раз и получить доступ ко всем ресурсам без повторной аутентификации на каждом из них. Эта возможность оптимизирует UX, снижая трение, и особенно ценна для компаний в международной среде или с мультисервисными платформами.

Метод signalAllAcceptedCredentials(options) предоставляет полный список идентификаторов учетных данных WebAuthn (Credential IDs) для данного пользователя. Проверяющим сторонам следует использовать этот метод вместо signalUnknownCredential(), когда пользователь уже аутентифицирован, так как в этом случае нет риска утечки приватных данных. Этот метод предлагает полный обзор публичных ключей пользователя, включая любые недавние изменения, которые могли быть не обновлены на подключенных в данный момент аутентификаторах.

Рассмотрим пример. У пользователя (userId: A) есть 2 passkeys с идентификаторами (Credential IDs), закодированными в Base64URL как X и Y. Затем пользователь удаляет passkey X в настройках аккаунта веб-сервиса (example.com), так что публичный ключ удаляется. Теперь выполним следующий код:

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "A", // WebAuthn User Handle, Base64URL.
    allAcceptedCredentialIds: ["Y"],
});

Если аутентификатор доступен во время выполнения этого кода, он удаляет или скрывает passkey X от будущих процедур аутентификации. Однако аутентификатор может быть не подключен в момент выполнения, поэтому рекомендуется периодически выполнять этот код, например, при каждом входе в систему.

Passkeys, отсутствующие в allAcceptedCredentialIds, будут удалены или скрыты, потенциально необратимо. Поэтому важно следить, чтобы действительные Credential IDs никогда не удалялись из списка. Если действительный Credential ID был случайно удален, проверяющая сторона должна немедленно включить его в следующий вызов signalAllAcceptedCredentials(options) как можно скорее, чтобы «открыть» passkey обратно. Если passkey был не скрыт, а удален, исправить это будет сложнее.

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

Try for Free

Метод signalCurrentUserDetails(options) сигнализирует текущее имя пользователя и отображаемое имя (Display Name) WebAuthn. При вызове этого метода клиент выполняет заданный набор шагов.

Рассмотрим пример. Пользователь с User ID A обновляет свое имя в настройках аккаунта на сайте (example.com). Затем проверяющая сторона может выполнить следующий код:

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "A", // user ID, Base64URL.
    name: "New user name",
    displayName: "New display name",
});

После этого аутентификатор обновит метаданные локально сохраненного passkey. Большое преимущество заключается в том, что в будущих запросах Conditional UI / автозаполнения passkeys меню выбора будет отображать обновленное имя.

Метод signalUnknownCredential(options) сигнализирует, что идентификатор Credential ID не распознан проверяющей стороной — например, если passkey был удален пользователем. В отличие от signalAllAcceptedCredentials(options), этот метод не требует предоставления полного списка принятых идентификаторов и WebAuthn User Handle, тем самым предотвращая потенциальные утечки данных неаутентифицированным вызывающим.

Рассмотрим пример. Пользователь удаляет passkey с Credential ID X в настройках аккаунта сайта (example.com), так что публичный ключ удаляется. Однако приватный ключ все еще доступен на устройстве пользователя. Это означает, что в будущих запросах входа через Conditional UI / автозаполнение passkeys (с пустым списком allowCredentials) этот passkey все еще можно будет выбрать. Однако попытка входа не удастся, поскольку публичный ключ уже удален. Поэтому проверяющая сторона должна выполнить:

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "X", // credential ID the user just tried, Base64URL
});

Тогда аутентификатор удалит или скроет passkey с идентификатором X из будущих сессий аутентификации.

Поскольку стандарт WebAuthn Level 3 все еще находится в статусе черновика, внедрение этих новых возможностей пока не носит массового характера. Различные браузеры постепенно реализуют эти функции, но поддержка варьируется. Ниже представлен актуальный обзор доступности в основных браузерах:

Темпы внедрения, вероятно, ускорятся по мере развития Level 3 и появления этих функций в большем количестве браузеров. Если вы хотите узнать, сколько пользователей могут воспользоваться getClientCapabilities() прямо сейчас, вы можете проверить реальные данные с помощью бесплатного ресурса State of Passkeys. Следите за примечаниями к релизам браузеров и документацией, чтобы планировать более широкую совместимость.

Want to find out how many people use passkeys?

View Adoption Data

Как разработчик, вы можете задаться вопросом, что означает обнаружение новых возможностей клиента WebAuthn для вас и как их использовать в приложении. Ниже вы найдете рекомендации по их применению.

Однако имейте в виду, что по состоянию на ноябрь 2024 года не все браузеры поддерживают вызов API getClientCapabilities(). Доступен полифилл здесь, который можно использовать, пока все браузеры не подтянутся.

Используйте getClientCapabilities() в начале вашего кода, чтобы обнаружить поддерживаемые клиентом функции при старте загрузки страницы или процесса аутентификации. Это позволит вам динамически настраивать UX, предоставляя функции passkeys, которые работают на устройстве или в браузере. Например, можно предлагать платформенную аутентификацию, когда она поддерживается, или альтернативные методы (например, SMS OTP или аппаратные ключи безопасности), когда её нет.

Если вы добавляете passkeys на сайт или в приложение, где сейчас используются пароли, функция conditionalCreate может стать настоящим драйвером для внедрения passkeys. В фоновом режиме во время автозаполнения паролей с подходящим менеджером (по состоянию на октябрь 2024 года это только Apple Passwords) passkey создается автоматически и будет предпочтительнее при будущих автозаполнениях.

Чтобы получить не только высокое внедрение passkeys, но и активное их использование для входа, проверяйте возможность использования Conditional UI / автозаполнения passkeys с помощью conditionalGet. Так вы будете подталкивать пользователей к применению созданного passkey для входа, так как он активно предлагается операционной системой или браузером и требует еще меньше усилий, чем автозаполнение пароля.

Используйте hybridTransport для обеспечения кросс-девайс аутентификации (через QR-код и Bluetooth), позволяя пользователям бесшовно входить в систему со смартфона, даже если они обращаются к вашему сервису с десктопа.

Возможности клиента WebAuthn — это важный шаг вперед в решении существующих пробелов в работе с passkeys. В этой статье мы разобрали ключевые вопросы о возможностях клиента WebAuthn:

1. Что такое возможности клиента WebAuthn? Мы объяснили, как эти функции позволяют браузерам и платформам сигнализировать о поддержке определенных возможностей, предоставляя разработчикам больше контроля над процессами аутентификации.
2. Какие возможности клиента существуют? Мы сделали обзор новых возможностей стандарта Level 3, включая getClientCapabilities, conditionalCreate, hybridTransport и другие.
3. Как они улучшают реализацию passkeys? Мы обсудили, как эти функции упрощают интеграцию, улучшают кросс-девайс использование и повышают безопасность.
4. Почему они важны для разработчиков? Эти возможности помогают создавать бесшовные, безопасные процессы аутентификации, которые соответствуют современным ожиданиям, делая внедрение проще и эффективнее.

Мы рекомендуем вам изучить новые возможности WebAuthn Level 3 и следить за их внедрением в браузерах. Если вы хотите реализовать passkeys и использовать эти продвинутые возможности, обращайтесь к нам за консультацией и поддержкой.

Вызывайте getClientCapabilities() в самом начале загрузки страницы или процесса аутентификации, чтобы динамически определять поддерживаемые функции. Это позволяет предлагать аутентификацию на платформе, когда она поддерживается, или использовать альтернативы (например, SMS OTP или аппаратные ключи), когда ее нет.

Для signalAllAcceptedCredentials требуется полный список действительных идентификаторов учетных данных и WebAuthn User Handle, поэтому его следует вызывать только после аутентификации пользователя во избежание утечки конфиденциальных данных. Метод signalUnknownCredential сообщает об одном неопознанном идентификаторе без необходимости предоставления полного списка, что делает его безопасным для использования в неаутентифицированных сценариях, например, после неудачной попытки входа.

Возможность relatedOrigins позволяет бесшовно аутентифицироваться в разных доменах, принадлежащих одной организации (например, amazon.com и amazon.de). Пользователи могут авторизоваться один раз и получить доступ ко всем ресурсам без повторной аутентификации на каждом домене, что снижает трение в международных или мультисервисных средах.

По состоянию на ноябрь 2024 года не все браузеры поддерживают getClientCapabilities(), поэтому в качестве временного решения можно использовать полифилл с github.com/MasterKale/webauthn-polyfills. Ожидается, что внедрение ускорится по мере развития стандарта WebAuthn Level 3, а Chrome 133, Edge 133, Firefox 135 и Safari 17.4 уже поставляются с его поддержкой.