WebAuthn Signal API: Обновление и удаление Passkeys на стороне клиента

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

Get Cheat Sheet

Последнее обновление: 4 ноября 2025 г.

Краткий обзор поддержки WebAuthn Signal API на различных платформах:

⚠️ Известная проблема: В Safari 26+ есть баг, из-за которого промис не разрешается должным образом (WebKit Bug #298951). Исправление ожидает слияния.

Экосистема Passkeys постоянно развивается. Чтобы способствовать этим изменениям, базовый стандарт WebAuthn тоже не стоит на месте. Новые функции часто начинаются с технического пояснения (explainer) на GitHub, а затем, после достаточного обсуждения, превращаются в pull request к стандарту. Недавно этот pull request был добавлен в черновик стандарта как WebAuthn Signal API. В этой статье мы разберем:

• Зачем нужен WebAuthn Signal API: Какие сценарии использования он поддерживает?
• Как работает WebAuthn Signal API: Как именно он устроен и какие рекомендации существуют для Relying Parties?

На момент написания статьи WebAuthn Signal API включен по умолчанию начиная с Chrome 132. Ранее он был известен как Reporting API, но был переименован, чтобы избежать конфликтов с другим API с таким же названием.

WebAuthn Signal API решает специфические задачи, связанные с управлением Passkeys на стороне клиента. В частности, он помогает поддерживать синхронизацию информации между Relying Party (RP) и аутентификаторами, которые являются частью операционных систем на стороне клиента. Существуют следующие важные сценарии использования:

Subscribe to our Passkeys Substack for the latest news.

Subscribe

При создании Passkey он включает несколько элементов информации: user.id, user.name и user.displayName. Сам Passkey идентифицируется с помощью уникального Credential ID.

• user.id: это уникальный идентификатор, представляющий аккаунт, с которым связан Passkey. Этот user.id критически важен, так как он используется для фактического сопоставления Passkey с аккаунтом пользователя.
• user.name и user.displayName: это метаданные, используемые исключительно для отображения в пользовательском интерфейсе.

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

Важно понимать, что хотя user.name (часто адрес электронной почты) и user.displayName (более дружелюбное, читаемое имя) помогают пользователю идентифицировать свой аккаунт в интерфейсе выбора, реальная связь между Passkey и аккаунтом поддерживается через user.id и Credential ID:

• У аккаунта может быть несколько Passkeys, но каждый Passkey уникально идентифицируется и сопоставляется с аккаунтом с помощью user.id.
• Каждый Passkey сам по себе имеет уникальный Credential ID, который генерируется аутентификатором.

Проблема возникает, когда user.name, которым может быть адрес электронной почты, меняется. В настоящее время не существует механизма для обновления этого изменения непосредственно на аутентификаторе на стороне клиента. user.name может измениться по разным причинам, например, если пользователь обновил свой email. Несмотря на это изменение в метаданных аккаунта на стороне сервера, старое user.name продолжит отображаться в интерфейсе выбора учетных данных, что может сбить пользователя с толку.

Обходной путь для этой проблемы — создать новый Passkey с обновленным user.name и тем же user.id, а затем перезаписать существующий Passkey. Однако этот подход неудобен по нескольким причинам:

1. Избыточность: Аутентификатор может хранить только один Passkey на user.id для конкретного ID Relying Party. Это означает, что старый Passkey нужно заменить новым только для обновления метаданных, что является лишним шагом.
2. Пользовательский опыт: Пользователи не поймут, зачем им создавать новый Passkey. Именно поэтому данный обходной путь не получил широкого распространения.
3. Сложность: Управление созданием Passkey и заменой только ради обновления метаданных создает ненужную сложность.

Email-адреса, номера телефонов и другие идентификаторы могут регулярно меняться. Без прямого метода обновления user.name и user.displayName непосредственно на аутентификаторе, пользователи могут столкнуться с постоянной проблемой, когда они видят и вынуждены выбирать Passkey, связанный со старым email. Эта ситуация подрывает бесшовный опыт, который призваны обеспечить Passkeys. WebAuthn Signal API нацелен решить эту проблему, позволяя Relying Parties сообщать об обновлении метаданных Passkeys без необходимости создания новых. Прежде чем мы объясним, как внедрить Signal API, давайте рассмотрим второй важный сценарий использования.

Become part of our Passkeys Community for updates & support.

Join

Другой важный сценарий — удаление Passkeys на аутентификаторе на стороне клиента. Со временем пользователи могут отозвать учетные данные через список управления Passkeys или удалить свои аккаунты. В таких случаях необходимо убедиться, что эти учетные данные удалены с клиентского аутентификатора, чтобы предотвратить их появление в будущих интерфейсах выбора (Conditional UI / автозаполнение Passkey).

Потребность в этой функциональности возникает в нескольких ситуациях:

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

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

2. Удаление аккаунта: Когда пользователь удаляет свой аккаунт, все связанные с ним Passkeys также должны быть удалены.
3. Политики безопасности: У Relying Parties могут быть политики безопасности, требующие отзыва учетных данных после периодов неактивности или из-за обнаруженных проблем с безопасностью.

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

Посмотрите это видео о том, как удалить Passkeys на стороне сервера в консоли управления Corbado Connect:

Внедрение WebAuthn Signal API включает несколько шагов и соображений для обеспечения корректной и безопасной интеграции. Signal API позволяет Relying Parties (RP) обновлять или удалять Passkey на аутентификаторе на стороне клиента. В этом разделе описаны ключевые моменты и шаги для реализации.

При внедрении WebAuthn Signal API крайне важно помнить о следующем:

• Сохранение конфиденциальности (Privacy Preserving): WebAuthn Signal API разработан с учетом сохранения конфиденциальности пользователей, так как это одна из основ WebAuthn. Это означает, что RP не получает обратной связи о том, было ли запрошенное изменение обработано. API работает «молча», чтобы предотвратить любую потенциальную утечку информации о состоянии учетных данных.
• Доступность аутентификатора: Эффективность WebAuthn Signal API зависит от доступности аутентификатора. Сюда входит как физическая доступность, так и программная поддержка (например, совместимость браузера и ОС). Браузер может выполнять действия только если аутентификатор доступен и поддерживает необходимые операции без требования биометрической аутентификации.
• Ограничения домена: API гарантирует, что только Relying Party, связанная с определенным доменом, может запрашивать изменения учетных данных, относящихся к этому домену. Это мера безопасности для предотвращения несанкционированных изменений третьими лицами.
• Credential ID как ключ: При ссылке на Passkeys основным ключом, используемым WebAuthn Signal API, является Credential ID. Этот ID уникально идентифицирует Passkey на аутентификаторе. API позволяет RP изменять метаданные, связанные с Passkeys, или сигнализировать, что определенные Passkeys больше не должны использоваться, но только через Credential ID. Если аутентификатор не знает конкретный Credential ID, он просто проигнорирует запрос.

Эти соображения необходимы для понимания наиболее важных аспектов корректной работы WebAuthn Signal API.

WebAuthn Signal API предоставляет упрощенный механизм для Relying Parties (RP) по обновлению метаданных, связанных с Passkeys на клиентских аутентификаторах. Это особенно важно для того, чтобы пользователи видели точную и актуальную информацию в интерфейсе выбора учетных данных без необходимости создавать новые Passkeys. Вот как API позволяет это сделать:

Обновление метаданных с помощью signalCurrentUserDetails(options)

Метод signalCurrentUserDetails(options) в Signal API специально разработан для обновления метаданных Passkeys. Этот метод позволяет RP предоставить текущие значения для user.name и user.displayName.

Вот как работает процесс (см. также стандарт WebAuthn Level 3):

1. Структура метода: Метод signalCurrentUserDetails(options) включает rp.id, user.id и обновленные значения для user.name и user.displayName.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    name: "New user name",
    displayName: "New display name",
});

2. Обновление локальных метаданных: Поиск локально доступных (на аутентификаторе) учетных данных, соответствующих rpId и userId. Для всех совпадающих учетных данных аутентификатор обновит name и displayName.
3. Сохранение конфиденциальности: Процесс спроектирован так, чтобы сохранять конфиденциальность. Signal API не предоставляет RP обратной связи о том, были ли обновления успешно обработаны, предотвращая утечку информации о состоянии учетных данных.
4. Согласованность между устройствами: Регулярно запуская метод signalCurrentUserDetails(options), RP могут гарантировать, что метаданные для Passkeys остаются согласованными на разных устройствах и платформах, где пользователь может аутентифицироваться. Такой подход снижает вероятность отображения устаревшей или неверной информации в интерфейсе выбора.

На скриншоте выше видно, как Google Chrome сигнализирует пользователю о таком обновлении. WebAuthn Signal API является частью Chrome и может быть протестирован с помощью Google Password Manager на десктопе.

WebAuthn Signal API предоставляет механизмы для Relying Parties (RP), чтобы сигнализировать об удалении Passkeys с клиентских аутентификаторов. Это необходимо для того, чтобы устаревшие или недействительные учетные данные не появлялись в интерфейсе выбора, поддерживая тем самым удобный и безопасный пользовательский опыт. Существует два метода для локального удаления Passkeys: signalUnknownCredential(options) и signalAllAcceptedCredentials(options). Первый можно использовать в ситуациях, когда пользователь не аутентифицирован, тогда как второй можно использовать, когда пользователь аутентифицирован. Поэтому второй метод предпочтительнее по соображениям конфиденциальности.

Вот как работают эти два метода:

1. Структура метода: Метод signalUnknownCredential(options) включает rpId (ID Relying Party) и credentialId (уникальный идентификатор удаляемой учетной записи).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // credential id, который пользователь только что попробовал, base64url
});

2. Вызов метода: RP вызывают этот метод, когда обнаруживают, что учетные данные должны быть удалены. Это может быть сразу после попытки аутентификации с недействительными учетными данными, во время удаления аккаунта или когда пользователь отзывает учетные данные через настройки.
3. Обработка метода: При вызове signalUnknownCredential(options) клиентский аутентификатор пытается найти учетные данные, соответствующие rpId и указанному credentialID, для исключения. В зависимости от возможностей аутентификатора, учетные данные либо удаляются, либо используется специфичная для аутентификатора процедура их скрытия в будущих церемониях аутентификации.

1. Структура метода: Метод signalAllAcceptedCredentials(options) включает rpId (ID Relying Party), userId и список действительных Credential ID allAcceptedCredentialIds (список уникальных идентификаторов учетных данных, которые следует сохранить).

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. Вызов метода: RP вызывают этот метод, когда обнаруживают, что какие-то учетные данные должны быть удалены, и передают список валидных данных. Этот метод предпочтительнее signalUnknownCredential(options) для удаления учетных данных.
3. Обработка метода: При вызове signalAllAcceptedCredentials(options) клиентский аутентификатор сопоставляет rpId и userId. Аутентификатор ищет все локальные учетные данные, соответствующие rpId и userId. Результат сравнивается с allAcceptedCredentialIds. Если есть локальные учетные данные, которых нет в allAcceptedCredentialIds, то они удаляются локально (или скрываются, в зависимости от аутентификатора).
4. Восстановление видимости (Unhide): Если учетные данные были только скрыты (в зависимости от аутентификатора) и теперь снова стали частью allAcceptedCredentialIds, то они снова появятся в будущих церемониях аутентификации.
5. Полезные советы:
   • При использовании signalAllAcceptedCredentials(options) важно учитывать, что аутентификаторы могут не всегда быть подключены в момент выполнения этого метода. В результате Relying Parties могут рассмотреть возможность периодического запуска signalAllAcceptedCredentials(options), например, при каждом входе в систему, чтобы гарантировать актуальность всех учетных данных.
   • Relying Parties должны быть осторожны при указании списка Credential ID (allAcceptedCredentialIds). Учетные данные, не включенные в этот список, могут быть скрыты или удалены аутентификатором, возможно, необратимо. Чтобы предотвратить ошибочное исключение валидных учетных данных, крайне важно убедиться в полноте списка. Если валидный Credential ID был случайно пропущен, его следует как можно скорее добавить обратно в signalAllAcceptedCredentials(options), чтобы сделать видимым снова (при условии, что аутентификатор это поддерживает).
   • Там, где это возможно, аутентификаторы должны предпочитать временное скрытие учетных данных вместо их безвозвратного удаления. Такой подход облегчает восстановление, если валидный Credential ID был случайно пропущен Relying Party, позволяя восстановить его без постоянной потери.

На скриншоте выше видно, как Google Chrome сигнализирует об удалении. WebAuthn Signal API можно протестировать с помощью Google Password Manager на десктопе.

Чтобы эффективно внедрить WebAuthn Signal API и обеспечить бесшовную синхронизацию метаданных Passkey между клиентскими аутентификаторами, рассмотрите следующие рекомендации:

• Следите за обновлениями WebAuthn Signal API и фактической реализацией: Будьте в курсе последних разработок и обновлений, связанных с Signal API. WebAuthn Signal API включен в Google Chrome 132, за ним следуют другие браузеры (например, Safari также объявил о поддержке). Регулярно проверяйте прогресс и обновления WebAuthn Signal API, чтобы убедиться, что ваша реализация соответствует последним стандартам и практикам. Мы будем обновлять этот пост по мере развития событий.
• Начните с подхода signalAllAcceptedCredentials(options) после каждого успешного входа: Этот подход гарантирует, что все метаданные и Credential ID обновляются одним методом, упрощая процесс и поддерживая согласованность на всех устройствах и платформах, и в то же время деактивирует удаленные или устаревшие учетные данные.
• Обмен сообщениями в реальном времени с signalUnknownCredential(options) для масштабных развертываний: Рассмотрите возможность использования обмена сообщениями в реальном времени с методом signalUnknownCredential(options) в масштабных развертываниях или когда требуется немедленное обновление. Этот метод может повысить эффективность и точность управления учетными данными, гарантируя, что недействительные или устаревшие данные будут оперативно удалены из интерфейса выбора.

Следуя этим рекомендациям, вы сможете эффективно внедрить WebAuthn Signal API, как только он станет поддерживаться, обеспечивая актуальность и согласованность метаданных Passkey на всех клиентских аутентификаторах, тем самым предоставляя плавный и безопасный пользовательский опыт.

Стандарт WebAuthn постоянно развивается, ежемесячно обрастая новыми функциями. Введение WebAuthn Signal API — это значительный шаг вперед в управлении метаданными и удалением Passkeys на клиентских аутентификаторах. Этот API решает важные задачи синхронизации информации между Relying Parties (RP) и аутентификаторами, а также гарантирует удаление недействительных или устаревших Passkeys, тем самым улучшая пользовательский опыт.

• Зачем нужен Signal API? Signal API необходим для обновления метаданных Passkeys и их удаления на клиентских аутентификаторах. Он решает проблемы, связанные с устаревшей информацией в user.name и user.displayName, которая может вызвать путаницу при отображении учетных данных в интерфейсе выбора. Кроме того, он помогает поддерживать чистоту и безопасность интерфейса выбора, удаляя отозванные или удаленные Passkeys.
• Как работает Signal API? Signal API позволяет RP вызывать методы, сообщающие о текущем состоянии учетных данных, включая обновление метаданных и сигналы об удалении Passkeys. Эти отчеты обрабатываются клиентским аутентификатором, гарантируя, что информация, представленная пользователям, является точной и актуальной. API разработан с учетом конфиденциальности и работает без предоставления RP обратной связи об успехе обновлений.

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