Представляем подсказки, запросы связанного происхождения и сериализацию JSON для WebAuthn в Chrome.

Chrome 128 и 129 представляют новые захватывающие функции для WebAuthn — базового API для создания систем аутентификации на основе паролей.

Eiji Kitamura

• Подсказки : Подсказки дают проверяющим сторонам (RP) лучший контроль над пользовательским интерфейсом WebAuthn в браузере. Они особенно полезны для корпоративных пользователей, которые хотят использовать ключи безопасности.
• Запросы на связанные источники : с запросами на связанные источники RP могут сделать пароли действительными на нескольких доменах. Если у вас есть несколько сайтов, вы теперь можете разрешить своим пользователям повторно использовать свой пароль на всех ваших сайтах, устраняя трение при входе.
• Сериализация JSON : API-интерфейсы сериализации JSON позволяют упростить код интерфейса RP путем кодирования и декодирования параметров и учетных данных, передаваемых в API WebAuthn и из него.

Подсказки

С помощью hints проверяющие стороны (RP) теперь могут указывать предпочтения пользовательского интерфейса для создания ключа доступа или аутентификации с помощью ключа доступа.

Раньше, когда RP хотел ограничить аутентификатор, который пользователь может использовать для создания ключа доступа или аутентификации, он мог использовать authenticatorSelection.authenticatorAttachment для указания "platform" или "cross-platform" . Они соответственно ограничивают аутентификатор аутентификатором платформы или роуминговым аутентификатором . С hints эта спецификация может быть более гибкой.

RP может использовать необязательные hints в PublicKeyCredentialCreationOptions или PublicKeyCredentialRequestOptions для указания "security-key" , "client-device" и "hybrid" в порядке предпочтения в массиве.

Ниже приведен пример запроса на создание учетных данных, который предпочитает "cross-platform" аутентификаторы с "security-key" в качестве подсказки. Это сообщает Chrome о необходимости отображения пользовательского интерфейса, ориентированного на ключ безопасности, для корпоративных пользователей.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

Когда RP хочет отдать приоритет сценарию проверки между устройствами, он может отправить запрос на аутентификацию, в котором предпочтение отдается "cross-platform" аутентификаторам с подсказкой "hybrid" .

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    residentKey: true,
    hints: ['hybrid']
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

Сопутствующие запросы о происхождении

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

Все запросы WebAuthn должны указывать идентификатор проверяющей стороны (RP ID), а все ключи доступа связаны с одним RP ID. Традиционно источник мог указывать только RP ID на основе своего домена, поэтому в этом случае www.example.co.uk мог указывать RP ID example.co.uk , но не example.com . С помощью связанных запросов источника заявленный RP ID может быть проверен путем извлечения известного файла JSON, расположенного по адресу /.well-known/webauthn из целевого домена. Таким образом, example.co.uk (и example.in , example.de и т. д.) могли бы использовать RP ID example.com , если example.com указывает их в следующем формате:

URL-адрес: https://example.com/.well-known/webauthn

{
  "origins": [
    "https://example.co.uk",
    "https://example.de",
    "https://example.sg",
    "https://example.net",
    "https://exampledelivery.com",
    "https://exampledelivery.co.uk",
    "https://exampledelivery.de",
    "https://exampledelivery.sg",
    "https://myexamplerewards.com",
    "https://examplecars.com"
  ]
}

Узнайте, как настроить запросы Related Origin, в статье Разрешите повторное использование ключа доступа на ваших сайтах с помощью запросов Related Origin .

JSON-сериализация

Объекты запроса и ответа WebAuthn имеют несколько полей, которые содержат необработанные двоичные данные в ArrayBuffer, такие как идентификатор учетных данных, идентификатор пользователя или вызов. Если веб-сайт хочет использовать JSON для обмена этими данными со своим сервером, двоичные данные должны быть сначала закодированы, например, с помощью Base64URL. Это добавляет ненужную сложность для разработчиков, которые хотят начать использовать пароли на своих веб-сайтах.

WebAuthn теперь предлагает API для разбора объектов запроса PublicKeyCredentialCreationOptions и PublicKeyCredentialRequestOptions WebAuthn напрямую из JSON и сериализации ответа PublicKeyCredential напрямую в JSON. Все поля со значениями ArrayBuffer, которые содержат необработанные двоичные данные, автоматически преобразуются из или в их значения, закодированные в Base64URL. Эти API доступны с Chrome 129.

Перед созданием ключа доступа извлеките с сервера объект PublicKeyCredentialCreationOptions , закодированный в формате JSON, и декодируйте его с помощью PublicKeyCredential.parseCreationOptionsFromJSON() .

export async function registerCredential() {

  // Fetch encoded `PublicKeyCredentialCreationOptions`
  // and JSON decode it.
  const options = await fetch('/auth/registerRequest').json();

  // Decode `PublicKeyCredentialCreationOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseCreationOptionsFromJSON(options);  

  // Invoke the WebAuthn create() function.
  const cred = await navigator.credentials.create({
    publicKey: decodedOptions,
  });
  ...

После создания ключа доступа закодируйте полученные учетные данные с помощью toJSON() чтобы их можно было отправить на сервер.

  ...
  const cred = await navigator.credentials.create({
    publicKey: options,
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch('/auth/registerResponse', credential);
  ...

Перед аутентификацией с помощью ключа доступа извлеките с сервера закодированный в JSON параметр PublicKeyRequestCreationOptions и декодируйте его с помощью PublicKeyCredential.parseRequestOptionsFromJSON() .

export async function authenticate() {

  // Fetch encoded `PublicKeyCredentialRequestOptions`
  // and JSON decode it.
  const options = await fetch('/auth/signinRequest').json();

  // Decode `PublicKeyCredentialRequestOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseRequestOptionsFromJSON(options);

  // Invoke the WebAuthn get() function.
  const cred = await navigator.credentials.get({
    publicKey: options
  });
  ...

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

  ...
  const cred = await navigator.credentials.get({
    publicKey: options
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch(`/auth/signinResponse`, credential);
  ...

Узнать больше

Чтобы узнать больше о WebAuthn и паролях, ознакомьтесь со следующими ресурсами:

• Пароли | Chrome для разработчиков
• Введение в реализацию ключа доступа на стороне сервера
• passkeys.dev