9 библиотек серверов WebAuthn: сравнение и выбор

Шпаргалка по Passkeys. Практические рекомендации, шаблоны внедрения и KPI для программ passkeys.

Получить шпаргалку

Обеспечение безопасной и простой аутентификации пользователей — обязательное требование для цифровых компаний в 2024 году. Ключи доступа (passkeys), как новый стандарт входа в систему, являются идеальным решением для удовлетворения этих потребностей. Однако повышенное удобство и безопасность ключей доступа для пользователей обходятся разработчикам дорогой ценой при их реализации. Сложность внедрения связана с тем, что ключи доступа — относительно новая технология не только для пользователей, но и для разработчиков, и их реализация может быть довольно сложной по сравнению с аутентификацией на основе паролей. На самом деле для аутентификации по ключам доступа требуется как минимум четыре конечные точки API, в то время как для аутентификации по паролю — всего одна.

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

Источник: Yubico

В этой статье блога мы сравниваем несколько библиотек / пакетов / SDK серверов WebAuthn, анализируем их различия и даем рекомендации разработчикам, которые только начинают внедрять ключи доступа.

Чтобы лучше понять, зачем вообще нужна библиотека сервера WebAuthn, давайте посмотрим, как можно внедрить ключи доступа. В принципе, существует два способа интеграции ключей доступа на веб-сайты и в приложения:

1. Использовать стороннее решение для ключей доступа (например, Corbado).
2. Реализовать ключи доступа самостоятельно с помощью одной из библиотек серверов WebAuthn, перечисленных ниже.

Хотя стороннее решение легко интегрировать, и оно обычно экономит много времени инженеров (особенно на пограничные случаи, обслуживание, восстановление, резервные варианты и улучшенный UX), некоторые разработчики предпочитают реализовывать все самостоятельно.

Попробуйте passkeys в live demo.

Попробовать passkeys

Давайте посмотрим, как работает самостоятельная реализация ключей доступа. В самой базовой настройке необходим механизм для регистрации (sign-up) и аутентификации (login). Оба процесса, также называемые церемониями WebAuthn, обрабатываются по-разному, хотя общий поток следует похожей схеме:

1. Фронтенд (браузер) инициирует запрос на регистрацию или вход и вызывает конечную точку API бэкенда.
2. Бэкенд генерирует параметры WebAuthn для регистрации или входа. Они называются PublicKeyCredentialCreationOptions и PublicKeyCredentialRequestOptions соответственно. Одной из важнейших частей этих параметров является вызов (challenge). Затем параметры WebAuthn отправляются обратно на фронтенд.
3. Фронтенд получает эти параметры и использует их для подтверждения личности пользователя с помощью локальной системы аутентификации устройства (например, Face ID, Touch ID, Windows Hello). В процессе регистрации создается новая пара открытого и закрытого ключей, закрытый ключ сохраняется локально, а открытый отправляется на сервер. При входе вызов подписывается с помощью закрытого ключа и отправляется на другую конечную точку API бэкенда.
4. В процессе регистрации бэкенд получает открытый ключ и сохраняет его. При входе бэкенд получает подписанный вызов и проверяет его целостность с помощью сервера WebAuthn.

Поскольку каждый процесс регистрации или входа включает эти этапы, бэкенду необходимо отслеживать пользователей, ключи доступа и запросы.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

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

В реальных сценариях при самостоятельной реализации ключей доступа имейте в виду, что дело не только в предоставлении необходимых конечных точек API и базовой реализации. Кроме того, вам необходимо решить следующие задачи и сценарии использования:

• Управление устройствами
• Кроссплатформенные и кросс-девайсные процессы входа
• Управление пользователями
• Управление сессиями
• Обнаружение готовности устройств к работе с ключами доступа
• Обучение пользователей
• Резервные методы аутентификации
• Механизмы восстановления
• Опции для совместного использования аккаунтов
• Оптимизированные процессы создания ключей доступа и входа для высокого уровня принятия

Тем не менее, для базовой реализации вам нужно лишь придерживаться стандарта WebAuthn. Использования хорошо известной и поддерживаемой библиотеки сервера WebAuthn обычно достаточно. Библиотека генерирует параметры и проверяет вызовы при входе, по сути, беря на себя криптографическую и самую сложную часть.

Присоединяйтесь к нашему Passkeys Community для обновлений и поддержки.

Присоединиться

Все проанализированные библиотеки предоставляют необходимые функции для аутентификации по ключам доступа. Поэтому мы уделили особое внимание следующим критериям:

• Критерии выбора аутентификатора: Как можно задать предпочтения для определенного поведения и функций безопасности (например, принудительное создание резидентных ключей)?
• Глобальные настройки: Насколько можно централизовать необходимую конфигурацию?
• Документация: Насколько хорошо документирована библиотека и легко ли ей следовать?
• Примеры: Есть ли примеры реализаций, которые можно взять за основу?

Были проанализированы следующие библиотеки серверов WebAuthn (отсортированы по убыванию количества звезд на GitHub в декабре 2023 года):

Посмотрите, сколько людей действительно используют passkeys.

Посмотреть данные внедрения

• Язык программирования: Typescript
• Фреймворк: Node.js
• Автор: Matthew Miller (Duo Security / Cisco)
• Звезды: 1 000
• Используется: 781
• Контрибьюторы: 19
• Соответствие FIDO: Да
• Глобальные настройки: Нет
• Критерии выбора аутентификатора: Как предложено W3C (должны содержать переменные authenticatorAttachment, residentKey, requireResidentKey и userVerification)
• Документация: Отлично структурирована с акцентом на быструю настройку и простоту использования.
• Примеры: Пример проекта доступен в документации.
• Рекомендуемые структуры данных:

type UserModel = {
  id: string;
  username: string;
  currentChallenge?: string;
};
 
/**
 * It is strongly advised that authenticators get their own DB
 * table, ideally with a foreign key to a specific UserModel.
 *
 * "SQL" tags below are suggestions for column data types and
 * how best to store data received during registration for use
 * in subsequent authentications.
 */
type Authenticator = {
  // SQL: Encode to base64url then store as `TEXT`. Index this column
  credentialID: Uint8Array;
  // SQL: Store raw bytes as `BYTEA`/`BLOB`/etc...
  credentialPublicKey: Uint8Array;
  // SQL: Consider `BIGINT` since some authenticators return atomic timestamps as counters
  counter: number;
  // SQL: `VARCHAR(32)` or similar, longest possible value is currently 12 characters
  // Ex: 'singleDevice' | 'multiDevice'
  credentialDeviceType: CredentialDeviceType;
  // SQL: `BOOL` or whatever similar type is supported
  credentialBackedUp: boolean;
  // SQL: `VARCHAR(255)` and store string array as a CSV string
  // Ex: ['usb' | 'ble' | 'nfc' | 'internal']
  transports?: AuthenticatorTransport[];
};

• Другие характеристики: Отличный WebAuthn Debugger и наличие клиентской библиотеки.
• Личная оценка: Самая интуитивная настройка.
• Ссылка на GitHub: https://github.com/MasterKale/SimpleWebAuthn

• Язык программирования: C#
• Фреймворк: .NET
• Авторы: Anders Åberg, Alex Seigler
• Звезды: 962
• Используется: 200
• Контрибьюторы: 40
• Соответствие FIDO: Да
• Глобальные настройки: Да
• Критерии выбора аутентификатора: Как предложено W3C
• Документация: Только Readme с несколькими примерами, немного passkey intelligence на сайте библиотеки.
• Примеры: Доступны демо-контроллер и пример хранилища учетных данных.
• Рекомендуемая структура данных:

public class StoredCredential
{
    /// <summary>
    /// The Credential ID of the public key credential source.
    /// </summary>
    public byte[] Id { get; set; }
 
    /// <summary>
    /// The credential public key of the public key credential source.
    /// </summary>
    public byte[] PublicKey { get; set; }
 
    /// <summary>
    /// The latest value of the signature counter in the authenticator data from any ceremony using the public key credential source.
    /// </summary>
    public uint SignCount { get; set; }
 
    /// <summary>
    /// The value returned from getTransports() when the public key credential source was registered.
    /// </summary>
    public AuthenticatorTransport[] Transports { get; set; }
 
    /// <summary>
    /// The value of the BE flag when the public key credential source was created.
    /// </summary>
    public bool IsBackupEligible { get; set; }
 
    /// <summary>
    /// The latest value of the BS flag in the authenticator data from any ceremony using the public key credential source.
    /// </summary>
    public bool IsBackedUp { get; set; }
 
    /// <summary>
    /// The value of the attestationObject attribute when the public key credential source was registered.
    /// Storing this enables the Relying Party to reference the credent’al's attestation statement at a later time.
    /// </summary>
    public byte[] AttestationObject { get; set; }
 
    /// <summary>
    /// The value of the clientDataJSON attribute when the public key credential source was registered.
    /// Storing this in combination with the above attestationObject item enables the Relying Party to re-verify the attestation signature at a later time.
    /// </summary>
    public byte[] AttestationClientDataJson { get; set; }
 
    public List<byte[]> DevicePublicKeys { get; set; }
 
    public byte[] UserId { get; set; }
 
    public PublicKeyCredentialDescriptor Descriptor { get; set; }
 
    public byte[] UserHandle { get; set; }
 
    public string AttestationFormat { get; set; }
 
    public DateTimeOffset RegDate { get; set; }
 
    public Guid AaGuid { get; set; }
}

• Другие характеристики: Используется Bitwarden.
• Личная оценка: Удобная для разработчиков библиотека с хорошим набором дополнительных материалов.
• Ссылка на GitHub: https://github.com/passwordless-lib/fido2-net-lib

• Язык программирования: Python
• Фреймворк: Нет конкретного
• Автор: Duo Labs
• Звезды: 727
• Используется: 912
• Контрибьюторы: 23
• Соответствие FIDO: Н/Д
• Глобальные настройки: Нет
• Критерии выбора аутентификатора: Как предложено W3C
• Документация: Практически отсутствует, требуются предварительные знания о ключах доступа.
• Примеры: Включены небольшие примеры кода для регистрации и входа.
• Рекомендуемая структура данных: Н/Д
• Другие характеристики: Требуется Python >= 3.8
• Личная оценка: Сравнительно компактная библиотека с небольшим количеством файлов.
• Ссылка на GitHub: https://github.com/duo-labs/py_webauthn

• Язык программирования: Ruby
• Фреймворк: Ruby on Rails
• Автор: Cedarcode
• Звезды: 580
• Используется: 679
• Загрузки Gem: 18 млн
• Контрибьюторы: 27
• Соответствие FIDO: Да
• Глобальные настройки: Да
• Критерии выбора аутентификатора: Как предложено W3C
• Документация: Readme — единственный источник документации.
• Примеры: Н/Д
• Рекомендуемая структура данных: Н/Д
• Другие характеристики: Доступны обертки для этой библиотеки (warden-webauthn, devise-passkeys).
• Личная оценка: Поскольку дополнительных материалов довольно мало, мы рекомендуем эту библиотеку, только если вы знакомы как с Ruby, так и с ключами доступа.
• Ссылка на GitHub: https://github.com/cedarcode/webauthn-ruby

• Язык программирования: Go
• Фреймворк: Фреймворки на базе Go (Gin, Echo и т.д.)
• Автор: Изначально Duo Labs / продолжил James Elliott
• Звезды: 480
• Используется: 280
• Контрибьюторы: 18
• Соответствие FIDO: Да
• Глобальные настройки: Да
• Критерии выбора аутентификатора: Как предложено W3C
• Документация: Readme с некоторыми примерами.
• Примеры: Доступен репозиторий с примерами.
• Рекомендуемая структура данных: Н/Д
• Другие характеристики: Большое количество файлов.
• Личная оценка: Популярная библиотека, простая в использовании, когда вы с ней освоитесь.
• Ссылка на GitHub: https://github.com/go-webauthn/webauthn

• Язык программирования: Java
• Фреймворк: Maven / Gradle
• Автор: Yubico
• Звезды: 391
• Используется: Н/Д
• Контрибьюторы: 27
• Соответствие FIDO: Н/Д
• Глобальные настройки: Да
• Критерии выбора аутентификатора: Как предложено W3C.
• Документация: Readme — единственная, но довольно подробная документация.
• Примеры: Н/Д
• Рекомендуемая структура данных: Н/Д
• Другие характеристики: Поставляется с интерфейсом Credential Repository, предоставляющим четкие инструкции по необходимым методам извлечения данных из БД.
• Личная оценка: Хотя вам придется управлять базой данных самостоятельно, репозиторий учетных данных значительно помогает в процессе проектирования БД.
• Ссылка на GitHub: https://github.com/Yubico/java-webauthn-server

• Язык программирования: Rust
• Фреймворк: На базе Rust (Rocket, Axum и т.д.)
• Автор: Kanidm Identity Management Project
• Звезды: 351
• Используется: 617
• Контрибьюторы: 25
• Соответствие FIDO: Н/Д
• Глобальные настройки: Да
• Критерии выбора аутентификатора: Очень ограниченные возможности настройки по сравнению с другими.
• Документация: Существует автоматически генерируемая техническая документация, но она не очень подробная.
• Примеры: Доступен репозиторий с руководством с примерами для 3 различных веб-фреймворков.
• Рекомендуемая структура данных: Н/Д
• Другие характеристики: Библиотека прошла аудит безопасности, проведенный отделом безопасности продуктов SUSE.
• Личная оценка: Из-за ограниченных возможностей конфигурации и документации мы рекомендуем эту библиотеку, только если вашим основным фреймворком является фреймворк на базе Rust.
• Ссылка на GitHub: https://github.com/kanidm/webauthn-rs

• Язык программирования: PHP
• Фреймворк: Symfony
• Автор: Florent Morselli
• Звезды: 347
• Используется: Н/Д
• Контрибьюторы: 18
• Соответствие FIDO: Да
• Глобальные настройки: Да
• Критерии выбора аутентификатора: Как предложено W3C.
• Документация: Обширная документация, включающая технические детали, а также объясняющая ключи доступа с нуля.
• Примеры: Доступен репозиторий с примерами.
• Рекомендуемая структура данных:

<?php
 
declare(strict_types=1);
 
namespace App\Entity;
 
use App\Repository\PublicKeyCredentialSourceRepository;
use DateTimeImmutable;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Uid\AbstractUid;
use Symfony\Component\Uid\Uuid;
use Webauthn\PublicKeyCredentialSource as BasePublicKeyCredentialSource;
use Webauthn\TrustPath\TrustPath;
 
#[ORM\Table(name: 'pk_credential_sources')]
#[ORM\Entity(repositoryClass: PublicKeyCredentialSourceRepository::class)]
class PublicKeyCredentialSource extends BasePublicKeyCredentialSource
{
    #[ORM\Column(type: Types::DATETIME_IMMUTABLE)]
    public readonly DateTimeImmutable $createdAt;
 
    #[ORM\Id]
    #[ORM\Column(type: Types::STRING, length: 255)]
    #[ORM\GeneratedValue(strategy: 'NONE')]
    private string $id;
 
    public function __construct(
        string $publicKeyCredentialId,
        string $type,
        array $transports,
        string $attestationType,
        TrustPath $trustPath,
        AbstractUid $aaguid,
        string $credentialPublicKey,
        string $userHandle,
        int $counter
    ) {
        $this->id = Uuid::v4()->toRfc4122();
        $this->createdAt = new DateTimeImmutable();
        parent::__construct($publicKeyCredentialId, $type, $transports, $attestationType, $trustPath, $aaguid, $credentialPublicKey, $userHandle, $counter);
    }
 
    public function getId(): string
    {
        return $this->id;
    }
}

• Другие характеристики: Н/Д
• Личная оценка: Хорошо подходит для людей, которые хотят изучить ключи доступа, но не имеют предварительных знаний.
• Ссылка на GitHub: https://github.com/web-auth/webauthn-framework

• Язык программирования: Java
• Фреймворк: Maven
• Автор: WebAuthn4j
• Звезды: 342
• Используется: Н/Д
• Контрибьюторы: 19
• Соответствие FIDO: Да
• Глобальные настройки: Да
• Критерии выбора аутентификатора: Вместо предложенного W3C параметра UserVerificationRequirement, webauthn4j предлагает verificationRequired и userPresenceRequired.
• Документация: Сухая, но обширная документация с несколькими примерами кода.
• Примеры: Доступен репозиторий с примерами.
• Рекомендуемая структура данных: Н/Д
• Другие характеристики: Н/Д
• Личная оценка: Документация сосредоточена исключительно на функциональности.
• Ссылка на GitHub: https://github.com/webauthn4j/webauthn4j

В следующей таблице представлен обзор библиотек серверов WebAuthn:

Подпишитесь на наш Passkeys Substack, чтобы получать новости.

Подписаться

Поскольку большинство библиотек одинаково мощны и реализуют стандарт WebAuthn, мы рекомендуем следующее дерево решений:

• Доступна библиотека сервера WebAuthn на вашем фреймворке и языке программирования: В этом случае выберите ее, так как она позволяет нативно внедрить вызовы API WebAuthn в текущую структуру вашего фреймворка.
• Доступна библиотека сервера WebAuthn на вашем языке программирования: Выберите библиотеку на вашем родном языке программирования, чтобы она могла быть нативно встроена в ваши текущие конечные точки API.
• Нет доступной библиотеки сервера WebAuthn на вашем языке программирования: В этом случае вам следует рассмотреть использование управляемого решения, такого как Corbado. Если это не вариант, мы рекомендуем использовать go-webauthn или SimpleWebAuthn.

Если вы просто хотите узнать больше о серверах WebAuthn в целом, мы можем дать несколько рекомендаций:

• Для быстрого тестирования: пакет py_webauthn предлагает мгновенную реализацию с готовыми к использованию фрагментами кода.
• Для интуитивно понятной реализации: пакет SimpleWebauthn, написанный на Typescript, прямолинеен и удобен для разработчиков.
• Для глубокого понимания: библиотека webauthn-framework для PHP выделяется обширной и структурированной документацией, ориентированной на концепции ключей доступа.

Для еще более глубокого понимания того, как работает WebAuthn на стороне сервера, вы можете прочитать очень подробный раздел "WebAuthn Relying Party Operations" в RFC WebAuthn, который детализирует каждый шаг, необходимый для регистрации новых учетных данных (7.1) и проверки утверждения аутентификации (7.2).

Оцените ваши конкретные требования к ключам доступа и WebAuthn. Прочитайте о параметрах PublicKeyCredentialCreationOptions и PublicKeyCredentialRequestOptions вместе с клиентскими вызовами API WebAuthn navigator.credentials.create() и navigator.credentials.get().

Для всех библиотек серверов WebAuthn вам потребуется предоставить соответствующую структуру базы данных для хранения и доступа к следующей информации:

• Учетные данные (Credentials)
• Пользователи (Users)
• Вызовы (Challenges)
• Аутентификаторы (Authenticators)

Крайне важно полностью понимать, какие поля WebAuthn необходимо хранить и где. Обратите особое внимание на то, какое значение вы хотите использовать для идентификатора пользователя (user.id). Также примите во внимание, что происходит, когда пользователь может удалить ключ доступа. Список действительных аутентификаторов, связанных с ключами доступа, можно найти здесь. Дополнительную информацию можно найти здесь.

Определите, на каких устройствах ваши пользователи будут использовать ключи доступа и резервные методы аутентификации. Если вы не уверены, проверьте State of Passkeys для получения последних данных о готовности к работе с ключами доступа. С точки зрения наблюдаемости (observability), храните клиентские сбои WebAuthn и отклонения при проверке сервером как отдельные потоки данных. Кроме того, следует помнить, что для Windows 10 и Linux вам потребуется придумать специальные решения, поскольку эти операционные системы обеспечивают наименьшую (если вообще обеспечивают) поддержку ключей доступа.

Посмотрите, сколько людей действительно используют passkeys.

Посмотреть данные внедрения

В настоящее время почти для каждого языка или фреймворка существует хорошо зарекомендовавшая себя библиотека сервера WebAuthn. Сравнение библиотек не показывает явного превосходства определенных реализаций. Скорее вам следует использовать фреймворк или язык программирования, с которым вы лучше всего знакомы. В качестве альтернативы, если вы не хотите реализовывать WebAuthn самостоятельно, вы можете попробовать готовое решение, такое как Corbado. Вы можете попробовать его бесплатно с неограниченным количеством пользователей здесь.

О Corbado

Corbado — это Authentication Intelligence Platform для CIAM-команд, обеспечивающих аутентификацию пользователей в крупных масштабах. Мы показываем то, что не видят логи IDP и общие инструменты аналитики: какие устройства, версии ОС, браузеры и менеджеры учётных данных поддерживают passkey, почему регистрации не превращаются в логины, где сбоит WebAuthn-поток и когда обновление ОС или браузера тихо ломает вход — всё это без замены Okta, Auth0, Ping, Cognito или вашего собственного IDP. Два продукта: Corbado Observe добавляет наблюдаемость для passkey и любых других способов входа. Corbado Connect даёт managed passkey со встроенной аналитикой (рядом с вашим IDP). VicRoads использует passkey для более чем 5 млн пользователей с Corbado (+80 % активации passkey). Поговорить с экспертом по passkey →

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

Как минимум вы должны сохранять учетные данные, пользователей, вызовы (challenges) и аутентификаторы. Обратите пристальное внимание на то, какое значение вы назначаете в качестве идентификатора пользователя (userHandle), и спланируйте сценарии, при которых пользователи могут удалить ключ доступа (passkey) со своего устройства.

Библиотеки серверов WebAuthn обрабатывают самые сложные криптографические операции: генерацию параметров PublicKeyCredentialCreationOptions и PublicKeyCredentialRequestOptions, а также проверцию подписанных вызовов. Сделать это правильно с нуля значительно сложнее, чем использовать проверенную и прошедшую аудит библиотеку, соответствующую стандарту FIDO.

Windows 10 и Linux обеспечивают наименьшую поддержку ключей доступа, поэтому для пользователей этих платформ требуются специальные резервные решения. Мониторинг сбоев WebAuthn на стороне клиента и отклонений проверки сервером как отдельных потоков помогает выявлять проблемы, специфичные для ОС, в производственной среде.