Регистрация ключа доступа на стороне сервера

Обзор

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

Процесс регистрации ключа доступа

  • Задайте параметры для создания ключа доступа. Отправьте их клиенту, чтобы передать в вызов для создания ключа доступа: вызов 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, отправленный сервером
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 });
  }
});

Сохраните открытый ключ

PublicKeyCredentialCreationOptions, отправленный сервером
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содержит важную информацию об учетных данных открытого ключа, связанных с новым ключом доступа:

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

Приложение. Проверка ответа на запрос регистрации

Проверка ответа на регистрацию состоит из следующих этапов:

  • Убедитесь, что идентификатор проверяющей стороны соответствует вашему сайту.
  • Убедитесь, что запрос исходит из ожидаемого источника (основной URL сайта, приложение для Android).
  • Если вы требуете подтверждения пользователя, убедитесь, что для параметра authenticatorData.uv установлено значение true.
  • Обычно флаг присутствия пользователя authenticatorData.up должен иметь значение true, но если учетные данные созданы условно, то значение должно быть false.
  • Убедитесь, что клиент смог предоставить заданную вами задачу. Если вы не используете аттестацию, эта проверка не имеет значения. Однако мы рекомендуем реализовать эту проверку, чтобы ваш код был готов к использованию аттестации в будущем.
  • Убедитесь, что идентификатор учетных данных ещё не зарегистрирован ни для одного пользователя. У серверных библиотек FIDO нет доступа к вашей базе данных, поэтому вы должны реализовать эту проверку на своем сервере и отклонять дубликаты, а не перезаписывать, добавлять или удалять существующие учетные данные. Подробнее о том, как проверить уникальность идентификатора учетных данных…
  • Убедитесь, что алгоритм, используемый поставщиком ключей доступа для создания учетных данных, указан в списке (в каждом поле alg в publicKeyCredentialCreationOptions.pubKeyCredParams, которое обычно определяется в библиотеке на стороне сервера и не видно вам). Это гарантирует, что пользователи смогут регистрироваться только с помощью разрешенных вами алгоритмов.

Чтобы узнать больше, изучите исходный код SimpleWebAuthn для verifyRegistrationResponse или ознакомьтесь с полным списком проверок в спецификации.

Далее

Аутентификация с помощью ключа доступа на стороне сервера