Обзор
Ниже приведены основные этапы регистрации ключа доступа.

- Задайте параметры для создания ключа доступа. Отправьте их клиенту, чтобы передать в вызов для создания ключа доступа: вызов WebAuthn API
navigator.credentials.createв веб-версии иcredentialManager.createCredentialв Android. После того как пользователь подтвердит создание ключа доступа, вызов создания ключа доступа будет разрешен и вернет учетные данныеPublicKeyCredential. - Проверьте учетные данные и сохраните их на сервере.
Ниже приведены подробные инструкции для каждого шага.
Создать параметры создания учетных данных
Первое, что нужно сделать на сервере, – создать объект PublicKeyCredentialCreationOptions.
Для этого используйте библиотеку FIDO на стороне сервера. Обычно в ней есть служебная функция, которая может создать эти параметры. Например, SimpleWebAuthn предлагает generateRegistrationOptions.
PublicKeyCredentialCreationOptions должен включать все, что нужно для создания ключа доступа: информацию о пользователе, о проверяющей стороне и конфигурацию свойств создаваемых учетных данных. Определив все эти параметры, передайте их функции в серверной библиотеке FIDO, которая отвечает за создание объекта PublicKeyCredentialCreationOptions.
Некоторые поля PublicKeyCredentialCreationOptions могут быть константами. Другие должны динамически определяться на сервере:
rpIdЧтобы заполнить идентификатор RP на сервере, используйте функции или переменные на стороне сервера, которые предоставляют имя хоста вашего веб-приложения, напримерexample.com.user.nameиuser.displayName: Чтобы заполнить эти поля, используйте информацию о сеансе пользователя, выполнившего вход (или информацию о новом аккаунте пользователя, если новый пользователь создает ключ доступа при регистрации).user.name– это, как правило, адрес электронной почты, уникальный для проверяющей стороны.user.displayName– это удобное название. Обратите внимание, что не все платформы будут использоватьdisplayName.user.id– случайная уникальная строка, которая генерируется при создании аккаунта. Он должен быть постоянным, в отличие от имени пользователя, которое можно изменить. Идентификатор пользователя позволяет определить аккаунт, но не должен содержать информацию, позволяющую идентифицировать личность. Скорее всего, в вашей системе уже есть идентификатор пользователя, но при необходимости создайте его специально для ключей доступа, чтобы в нем не было информации, позволяющей идентифицировать личность.excludeCredentials– список идентификаторов существующих учетных данных, чтобы избежать дублирования ключа доступа от поставщика. Чтобы заполнить это поле, найдите в базе данных существующие учетные данные пользователя. Подробную информацию можно найти в разделе Запретить создание нового ключа доступа, если он уже существует.challenge. При регистрации учетных данных запрос не имеет значения, если вы не используете аттестацию – более продвинутый метод проверки личности поставщика ключа доступа и передаваемых им данных. Однако даже если вы не используете аттестацию, запрос все равно является обязательным полем. Инструкции по созданию безопасного запроса для аутентификации приведены в статье Аутентификация с помощью ключа доступа на стороне сервера.
Кодирование и декодирование
PublicKeyCredentialCreationOptions, отправленный сервером. Двоичные поля, такие как challenge и user.id, кодируются на стороне сервера в base64URL, чтобы параметры можно было передавать в формате JSON по протоколу HTTPS.Стандартный объект WebAuthn PublicKeyCredentialCreationOptions включает поля, которые являются ArrayBuffer, и их нельзя сериализовать напрямую с помощью JSON.stringify(). Чтобы передавать эти параметры по протоколу HTTPS, двоичные поля должны быть закодированы как строки base64URL:
- На сервере библиотека FIDO (например, SimpleWebAuthn) автоматически создает сериализуемый объект JSON (например,
PublicKeyCredentialCreationOptionsJSON) с полями, закодированными в Base64URL. - На стороне клиента современные браузеры поддерживают
PublicKeyCredential.parseCreationOptionsFromJSON()для преобразования параметров JSON непосредственно вPublicKeyCredentialCreationOptions. При использовании клиентских библиотек, таких как@simplewebauthn/browser, функции, подобныеstartRegistration({ optionsJSON: options }), выполняют это преобразование автоматически.
Пример кода: создание параметров создания учетных данных
В наших примерах используется библиотека SimpleWebAuthn. В этом случае мы передаем создание параметров учетных данных открытого ключа функции generateRegistrationOptions.
import {
generateRegistrationOptions,
verifyRegistrationResponse,
} from '@simplewebauthn/server';
import { isoBase64URL, isoUint8Array } from '@simplewebauthn/server/helpers';
router.post('/registerRequest', csrfCheck, sessionCheck, async (req, res) => {
const { user } = res.locals;
// Ensure you nest verification function calls in try/catch blocks.
// If something fails, throw an error with a descriptive error message.
// Return that message with an appropriate error code to the client.
try {
// `excludeCredentials` prevents users from re-registering existing
// credentials for a given passkey provider
const excludeCredentials = [];
const credentials = Credentials.findByUserId(user.id);
if (credentials.length > 0) {
for (const cred of credentials) {
excludeCredentials.push({
id: cred.id,
type: 'public-key',
transports: cred.transports,
});
}
}
// Generate registration options for WebAuthn create
const options = await generateRegistrationOptions({
rpName: process.env.RP_NAME,
rpID: process.env.HOSTNAME,
userID: isoUint8Array.fromUTF8String(user.id),
userName: user.username,
userDisplayName: user.displayName || '',
attestationType: 'none',
excludeCredentials,
authenticatorSelection: {
authenticatorAttachment: 'platform',
residentKey: 'required',
userVerification: 'preferred',
},
});
// Keep the challenge in the session
req.session.challenge = options.challenge;
return res.json(options);
} catch (e) {
console.error(e);
return res.status(400).send({ error: e.message });
}
});
Сохраните открытый ключ
navigator.credentials.create возвращает объект PublicKeyCredential.Если метод navigator.credentials.create успешно выполняется на клиенте, это означает, что ключ доступа создан. Возвращается объект PublicKeyCredential.
Объект PublicKeyCredential содержит объект AuthenticatorAttestationResponse, который представляет собой ответ поставщика ключа доступа на инструкцию клиента по созданию ключа доступа. Она содержит информацию о новых учетных данных, которые нужны вам как проверяющей стороне, чтобы в дальнейшем выполнять аутентификацию пользователя. Подробнее о AuthenticatorAttestationResponse рассказывается в приложенииAuthenticatorAttestationResponse.
Отправьте объект PublicKeyCredential на сервер. Когда вы его получите, подтвердите его.
Передайте этот шаг проверки библиотеке на стороне сервера FIDO. Обычно для этого используется служебная функция. Например, SimpleWebAuthn предлагает verifyRegistrationResponse. Подробнее о том, что происходит за кулисами, читайте в разделе Приложение. Проверка ответа на регистрацию.
После того как серверная библиотека FIDO проверит ответ, убедитесь, что идентификатор учетных данных уникален для всех пользователей, прежде чем сохранять учетные данные в базе данных.
Проверьте уникальность идентификатора учетных данных
Выполните запрос к базе данных, чтобы убедиться, что возвращенный идентификатор учетных данных (credential.id) ещё не зарегистрирован ни для одного пользователя, как того требуют шаги регистрации WebAuthn.
У серверных библиотек FIDO без сохранения состояния нет доступа к вашей базе данных, и они не могут проверять наличие повторяющихся идентификаторов учетных данных. Если идентификатор учетных данных уже существует в вашей базе данных, немедленно отклоните запрос на регистрацию.
Сохраните учетные данные в базе данных
После того как вы проверите ответ на регистрацию и убедитесь, что идентификатор учетных данных не используется, сохраните информацию об учетных данных в своей базе данных, чтобы пользователь мог позже пройти аутентификацию с помощью ключа доступа, связанного с этими учетными данными.
Используйте отдельную таблицу для учетных данных открытого ключа, связанных с ключами доступа. У пользователя может быть только один пароль, но несколько ключей доступа, например один, синхронизированный через Связку ключей Apple iCloud, и другой – через Google Менеджер паролей.
Ниже приведен пример схемы, которую можно использовать для хранения учетных данных.

- Таблица Users:
user_id– основной идентификатор пользователя. Случайный уникальный постоянный идентификатор пользователя. Используйте его в качестве первичного ключа для таблицы Users.username– имя пользователя, заданное пользователем и, возможно, доступное для редактирования.passkey_user_id– идентификатор пользователя, не содержащий информацию, позволяющую идентифицировать личность, и связанный с ключом доступа. Он представлен в видеuser.idв параметрах регистрации. Когда пользователь попытается выполнить аутентификацию, аутентификатор предоставит это значениеpasskey_user_idв ответе на запрос аутентификации вuserHandle. Мы не рекомендуем использоватьpasskey_user_idв качестве первичного ключа. Первичные ключи часто становятся информацией, позволяющей идентифицировать личность, поскольку они широко используются.
- Таблица учетных данных открытого ключа:
id– идентификатор учетных данных. Используйте его в качестве единственного первичного ключа (или примените глобальное ограничениеUNIQUEтолько кid) в таблице учетных данных открытого ключа. Не используйте составной ключ уникальности сpasskey_user_id, который позволяет использовать один и тот же идентификатор учетных данных в нескольких аккаунтах пользователей. Настройте вставку так, чтобы при конфликте уникальности она не выполнялась, а не перезаписывала или удаляла существующую строку.public_key– открытый ключ учетных данных.passkey_user_id– используйте это значение в качестве внешнего ключа, чтобы установить связь с таблицей Пользователи.backed_upКлюч доступа считается сохраненным в резервной копии, если он синхронизирован поставщиком ключей доступа. Хранение состояния резервной копии полезно, если вы хотите в будущем отказаться от паролей для пользователей, у которых есть ключи доступаbacked_up. Чтобы проверить, создана ли резервная копия ключа доступа, посмотрите на флаг BE вauthenticatorDataили воспользуйтесь функцией серверной библиотеки FIDO, которая обычно предоставляет доступ к этой информации. Сохранение информации о соответствии требованиям для резервного копирования может быть полезно для ответов на возможные запросы пользователей.name– необязательный параметр, который позволяет пользователям задавать собственные отображаемые названия для учетных данных.transports– массив transports. Хранение транспортов полезно для удобства аутентификации пользователей. Если способы передачи доступны, браузер может вести себя соответствующим образом и показывать интерфейс, который соответствует способу передачи, используемому поставщиком ключей доступа для связи с клиентами, в частности для случаев повторной аутентификации, когдаallowCredentialsне пусто.
Для удобства пользователей можно хранить и другую информацию, например поставщика ключа доступа, время создания учетных данных и время последнего использования. Подробнее о дизайне пользовательского интерфейса для ключей доступа…
Пример кода: сохранение учетных данных
В наших примерах используется библиотека SimpleWebAuthn.
Здесь мы передаем проверку ответа на регистрацию функции verifyRegistrationResponse.
import { isoBase64URL } from '@simplewebauthn/server/helpers';
router.post('/registerResponse', csrfCheck, sessionCheck, async (req, res) => {
const expectedChallenge = req.session.challenge;
const expectedOrigin = getOrigin(req.get('User-Agent'));
const expectedRPID = process.env.HOSTNAME;
const response = req.body;
// This sample code is for registering a passkey for an existing,
// signed-in user
// Ensure you nest verification function calls in try/catch blocks.
// If something fails, throw an error with a descriptive error message.
// Return that message with an appropriate error code to the client.
try {
// Verify the credential
const { verified, registrationInfo } = await verifyRegistrationResponse({
response,
expectedChallenge,
expectedOrigin,
expectedRPID,
requireUserVerification: false,
});
if (!verified) {
throw new Error('Verification failed.');
}
const {
aaguid,
credential,
credentialBackedUp
} = registrationInfo;
// Ensure the credential ID isn't already registered for any user.
// Stateless libraries like SimpleWebAuthn don't check your database for
// collisions.
const existingCredential = await Credentials.findById(credential.id);
if (existingCredential) {
throw new Error('Credential ID is already registered.');
}
// Name the credential based on AAGUID
const name =
aaguid === undefined ||
aaguid === '00000000-0000-0000-0000-000000000000' ?
req.useragent?.platform : aaguids[aaguid]?.name;
const base64PublicKey = isoBase64URL.fromBuffer(credential.publicKey);
// Existing, signed-in user
const { user } = res.locals;
// Insert the new credential. Use an insert-only operation (never an
// update or upsert) backed by a global unique constraint on `id` so
// concurrent duplicate requests fail instead of overwriting a credential.
await Credentials.create({
id: credential.id,
passkey_user_id: user.passkey_user_id,
publicKey: base64PublicKey,
name,
aaguid,
transports: credential.transports || response.response.transports,
backed_up: credentialBackedUp,
registered_at: new Date().getTime()
});
// Kill the challenge for this session
delete req.session.challenge;
return res.json(user);
} catch (e) {
delete req.session.challenge;
console.error(e);
return res.status(400).send({ error: e.message });
}
});
Приложение: AuthenticatorAttestationResponse
AuthenticatorAttestationResponse содержит два важных объекта:
response.clientDataJSON– это JSON-версия данных клиента, которые в интернете представляют собой данные, видимые браузеру. Он содержит источник RP, запрос иandroidPackageName, если клиент – приложение для Android. Как RP, чтениеclientDataJSONдает вам доступ к информации, которую браузер видел во время запросаcreate.response.attestationObjectсодержит два типа информации:attestationStatement, которое не имеет значения, если вы не используете аттестацию.authenticatorData– это данные, которые видит поставщик ключа доступа. Как проверяющая сторона, вы можете прочитатьauthenticatorData, чтобы получить доступ к данным, которые видит поставщик ключей доступа и которые возвращаются при запросеcreate.
authenticatorDataсодержит важную информацию об учетных данных открытого ключа, связанных с новым ключом доступа:
- Учетные данные открытого ключа и их уникальный идентификатор.
- Идентификатор проверяющей стороны, связанный с учетными данными.
- Флаги, описывающие статус пользователя при создании ключа доступа: присутствовал ли пользователь и был ли он успешно подтвержден (см. погружение в тему userVerification).
- AAGUID – это идентификатор поставщика ключей доступа, например Google Менеджера паролей. На основе AAGUID можно определить поставщика ключа доступа и показать его название на странице управления ключами доступа. (см. раздел Как определить поставщика ключей доступа с помощью AAGUID).
Хотя authenticatorData вложен в attestationObject, содержащаяся в нем информация необходима для реализации ключа доступа независимо от того, используете ли вы аттестацию. authenticatorData закодирован и содержит поля, закодированные в двоичном формате. Обычно синтаксический анализ и декодирование выполняет серверная библиотека. Если вы не используете серверную библиотеку, попробуйте задействовать getAuthenticatorData() на стороне клиента, чтобы не выполнять синтаксический анализ и декодирование на стороне сервера.
Приложение. Проверка ответа на запрос регистрации
Проверка ответа на регистрацию состоит из следующих этапов:
- Убедитесь, что идентификатор проверяющей стороны соответствует вашему сайту.
- Убедитесь, что запрос исходит из ожидаемого источника (основной URL сайта, приложение для Android).
- Если вы требуете подтверждения пользователя, убедитесь, что для параметра
authenticatorData.uvустановлено значениеtrue. - Обычно флаг присутствия пользователя
authenticatorData.upдолжен иметь значениеtrue, но если учетные данные созданы условно, то значение должно бытьfalse. - Убедитесь, что клиент смог предоставить заданную вами задачу. Если вы не используете аттестацию, эта проверка не имеет значения. Однако мы рекомендуем реализовать эту проверку, чтобы ваш код был готов к использованию аттестации в будущем.
- Убедитесь, что идентификатор учетных данных ещё не зарегистрирован ни для одного пользователя. У серверных библиотек FIDO нет доступа к вашей базе данных, поэтому вы должны реализовать эту проверку на своем сервере и отклонять дубликаты, а не перезаписывать, добавлять или удалять существующие учетные данные. Подробнее о том, как проверить уникальность идентификатора учетных данных…
- Убедитесь, что алгоритм, используемый поставщиком ключей доступа для создания учетных данных, указан в списке (в каждом поле
algвpublicKeyCredentialCreationOptions.pubKeyCredParams, которое обычно определяется в библиотеке на стороне сервера и не видно вам). Это гарантирует, что пользователи смогут регистрироваться только с помощью разрешенных вами алгоритмов.
Чтобы узнать больше, изучите исходный код SimpleWebAuthn для verifyRegistrationResponse или ознакомьтесь с полным списком проверок в спецификации.