PublicKeyCredentialCreationOptions

Базовая Широко поддерживается *

Эта функция хорошо зарекомендовала себя и работает на многих устройствах и версиях браузеров. Она доступна в браузерах с сентября 2021 года.

* Некоторые части этой функции могут иметь различный уровень поддержки.

Безопасный контекст: Эта функция доступна только в безопасных контекстах (HTTPS), в некоторых или всех поддерживающих браузерах.

Словарь PublicKeyCredentialCreationOptions представляет собой объект, передаваемый в CredentialsContainer.create() в качестве значения параметра publicKey: то есть при использовании create() для создания учетных данных с открытым ключом с помощью API аутентификации веб-приложений.

Свойства экземпляра

attestation Необязательно

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

"none": Указывает, что сторона, полагающаяся на данные, не заинтересована в аттестации аутентификатора. Это может быть сделано для того, чтобы избежать дополнительного согласия пользователя на обмен информацией с сервером стороны, полагающейся на данные, или на обмен данными с центром сертификации аттестации (CA) с целью упрощения процесса аутентификации. Если "none" выбрано в качестве значения attestation, а аутентификатор сигнализирует о том, что он использует CA для генерации заявления об аттестации, приложение клиента заменит его заявлением об аттестации «None», указывающим, что заявление об аттестации недоступно.
"direct": Указывает, что сторона, полагающаяся на данные, хочет получить заявление об аттестации, сгенерированное аутентификатором.
"enterprise": Указывает, что сторона, полагающаяся на данные, хочет получить заявление об аттестации, которое может содержать уникальную идентифицирующую информацию. Это предназначено для контролируемых развертываний в рамках предприятия, где организация хочет связать регистрации с конкретными аутентификаторами.
"indirect": Указывает, что сторона, полагающаяся на данные, хочет получить проверяемое заявление об аттестации, но позволит клиенту решить, как его получить. Например, клиент может заменить утверждение аутентификатора утверждением, сгенерированным центром анонимизации, чтобы защитить конфиденциальность пользователя.

Если attestation опущено, оно будет по умолчанию установлено в "none".

attestationFormats Необязательно

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

Если опущено, attestationFormats по умолчанию устанавливается в пустой массив.

authenticatorSelection Необязательно

Объект, свойства которого являются критериями, используемыми для фильтрации потенциальных аутентификаторов для операции создания учетных данных. Этот объект может содержать свойства:

authenticatorAttachment Необязательно

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

"platform"

Аутентификатор является частью устройства, на котором работает WebAuthn (называется платформенным аутентификатором), поэтому WebAuthn будет взаимодействовать с ним с использованием транспорта, доступного этой платформе, например, платформенно-специфического API. Учетная запись с открытым ключом, привязанная к платформенному аутентификатору, называется платформенной учетной записью.

"cross-platform"

Аутентификатор не является частью устройства, на котором работает WebAuthn (называется мобильным аутентификатором, поскольку он может перемещаться между различными устройствами), поэтому WebAuthn будет взаимодействовать с ним с использованием кросс-платформенного протокола связи, такого как Bluetooth или NFC. Учетная запись с открытым ключом, привязанная к мобильному аутентификатору, называется мобильной учетной записью.

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

requireResidentKey Необязательно

Булево значение. Если установлено в true, это означает, что требуется постоянный ключ (см. residentKey). Это свойство устарело, но все еще доступно в некоторых реализациях для обратной совместимости с WebAuthn Level 1. Значение должно быть установлено в true, если residentKey установлено в "required".

Если опущено, requireResidentKey по умолчанию устанавливается в false.

residentKey Необязательно

Строка, определяющая степень, в которой сторона, полагающаяся на данные, желает создать учетные данные, обнаруживаемые на стороне клиента (т.е., такие, которые могут использоваться в запросах аутентификации, где сторона, полагающаяся на данные, не предоставляет идентификаторы учетных данных — navigator.credentials.get() вызывается со значением пустого allowCredentials). Альтернативой является учетная запись на стороне сервера, где сторона, полагающаяся на данные, должна предоставить идентификаторы учетных данных в get() allowCredentials значении. Возможные значения:

"discouraged": Сторона, полагающаяся на данные, предпочитает создание учетной записи на стороне сервера, но примет учетные данные, обнаруживаемые на стороне клиента.
"preferred": Сторона, полагающаяся на данные, сильно предпочитает создание учетных данных, обнаруживаемых на стороне клиента, но примет учетные данные на стороне сервера. Агент пользователя должен направить пользователя по настройке проверки пользователя, если это необходимо, для создания обнаруживаемых учетных данных. Это имеет преимущество перед настройкой userVerification.
"required": Сторона, полагающаяся на данные, требует учетных данных, обнаруживаемых на стороне клиента. Если они не могут быть созданы, возникает ошибка.

Если опущено, residentKey по умолчанию устанавливается в "required", если requireResidentKey равно true, в противном случае значение по умолчанию — "discouraged".

userVerification Необязательно

Строка, определяющая требования стороны, полагающейся на данные, к проверке пользователя для операции create(). Возможные значения:

"discouraged": Сторона, полагающаяся на данные, предпочитает отсутствие проверки пользователя для операции create() в интересах минимизации нарушений пользовательского опыта.
"preferred": Сторона, полагающаяся на данные, предпочитает проверку пользователя для операции create(), но не завершит процесс, если проверка пользователя не может быть выполнена.
"required": Сторона, полагающаяся на данные, требует проверки пользователя для операции create() — если проверка пользователя не может быть выполнена, возникает ошибка.

Если опущено, userVerification по умолчанию устанавливается в "preferred".

challenge

Значение типа ArrayBuffer, TypedArray или DataView, предоставляемое сервером стороны, полагающейся на данные, и используемое в качестве криптографического запроса. Это значение будет подписано аутентификатором, и подпись будет возвращена в составе AuthenticatorAttestationResponse.attestationObject.

excludeCredentials Необязательно

Массив объектов, описывающих существующие учетные данные, уже сопоставленные с этой учетной записью пользователя (как определено user.id). Это предоставляется стороной, полагающейся на данные, и проверяется агентом пользователя, чтобы избежать создания новой учетной записи с открытым ключом на аутентификаторе, на котором уже существует сопоставленная учетная запись с указанной учетной записью пользователя. Каждый элемент должен иметь вид:

id: Значение типа ArrayBuffer, TypedArray или DataView, представляющее идентификатор существующей учетной записи.
transports Необязательно: Массив строк, представляющих разрешенные средства связи. Возможные средства связи: "ble", "hybrid", "internal", "nfc", и "usb" (см. getTransports() для получения дополнительной информации).
type: Строка, определяющая тип учетных данных с открытым ключом для создания. В настоящее время она может принимать единственное значение "public-key", но в будущем может быть добавлено больше значений.

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

Если excludeCredentials опущено, оно по умолчанию устанавливается в пустой массив.

extensions Необязательно

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

Расширения необязательны, и разные браузеры могут распознавать разные расширения. Обработка расширений всегда необязательна для клиента: если браузер не распознаёт данное расширение, он просто его проигнорирует. Сведения об использовании расширений и о том, какие расширения поддерживаются какими браузерами, см. в разделе Расширения аутентификации веб-сайта.

pubKeyCredParams

Массив объектов, которые определяют типы ключей и алгоритмы подписи, которые поддерживает сторона, полагающаяся на учетные данные, упорядоченные от наиболее предпочтительного к наименее предпочтительному. Клиент и аутентификатор сделают всё возможное, чтобы создать учетную запись наиболее предпочтительного типа. Эти объекты будут содержать следующие свойства:

alg

Число, равное идентификатору алгоритма COSE, представляющему криптографический алгоритм, который необходимо использовать для этого типа учетных данных. Рекомендуется, чтобы стороны, полагающиеся на учетные данные, которые хотят поддерживать широкий спектр аутентификаторов, включали по крайней мере следующие значения в предоставляемых вариантах:

-8: Ed25519
-7: ES256
-257: RS256

type

Строка, определяющая тип учетных данных открытого ключа, который необходимо создать. В настоящее время это может принимать одно значение, "public-key", но в будущем может быть добавлено больше значений.

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

rp

Объект, описывающий сторону, полагающуюся на учетные данные, которая запросила создание учетных данных. Он может содержать следующие свойства:

id Необязательно

Строка, представляющая идентификатор стороны, полагающейся на учетные данные. Учетные данные открытого ключа могут использоваться только для аутентификации с той же стороной, полагающейся на учетные данные (как идентифицировано в publicKey.rpId в вызове navigator.credentials.get()), с которой они были зарегистрированы — идентификаторы должны совпадать.

id не может включать порт или схему, как стандартный источник, но схема домена должна быть https схемой. id должно соответствовать эффективному домену источника или суффиксу домена. Например, если источником стороны, полагающейся на учетные данные, является https://login.example.com:1337, следующие значения id будут допустимыми:

login.example.com
example.com

Но не:

m.login.example.com
com

Если значение опущено, id по умолчанию устанавливается в документ origin — что в данном примере будет login.example.com.

name

Строка, представляющая имя стороны, полагающейся на учетные данные (например, "Facebook"). Это имя, которое будет представлено пользователю при создании или проверке операции WebAuthn.

timeout Необязательно

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

user

Объект, описывающий учетную запись пользователя, для которой генерируется учетная запись. Он может содержать следующие свойства:

displayName: Строка, предоставляющая удобочитаемое имя пользователя (например, "John Doe"), которое было установлено пользователем во время первоначальной регистрации на стороне, полагающейся на учетные данные.
id: ArrayBuffer, TypedArray или DataView, представляющие уникальный идентификатор учетной записи пользователя. Это значение имеет максимальную длину 64 байта и не предназначено для отображения пользователю.
name: Строка, предоставляющая удобочитаемый идентификатор учетной записи пользователя, чтобы помочь отличить различные учетные записи с похожими displayName. Это может быть адрес электронной почты (например, "john.doe@example.com"), номер телефона (например, "+12345678901") или другой вид идентификатора учетной записи пользователя (например, "johndoe667").

hints Необязательно

Массив строк, предоставляющий подсказки о том, какой пользовательский интерфейс аутентификации должен предоставить пользовательский агент для пользователя.

Значения могут быть любыми из следующих:

"security-key": Для аутентификации требуется отдельное физическое устройство для предоставления ключа.
"client-device": Пользователь проходит аутентификацию с использованием собственного устройства, например телефона.
"hybrid": Аутентификация основана на комбинации методов авторизации/аутентификации, потенциально использующих как механизмы пользователя, так и механизмы сервера.

Примеры

Создание учетных данных открытого ключа

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

Затем объект передаётся в navigator.credentials.create(), чтобы создать новые учетные данные открытого ключа.

const publicKey = {
  challenge: challengeFromServer,
  rp: { id: "acme.com", name: "ACME Corporation" },
  user: {
    id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]),
    name: "jamiedoe",
    displayName: "Jamie Doe",
  },
  pubKeyCredParams: [{ type: "public-key", alg: -7 }],
};

const publicKeyCredential = await navigator.credentials.create({ publicKey });

Успешный вызов create() возвращает обещание, которое разрешается с объектом PublicKeyCredential, представляющим учетные данные открытого ключа, которые позже могут быть использованы для аутентификации пользователя посредством вызова WebAuthn get(). Его свойство PublicKeyCredential.response содержит объект AuthenticatorAttestationResponse, предоставляющий доступ к нескольким полезным сведениям, включая данные аутентификатора, открытый ключ, механизмы транспорта и многое другое.

navigator.credentials.create({ publicKey }).then((publicKeyCredential) => {
  const response = publicKeyCredential.response;

  // Access attestationObject ArrayBuffer
  const attestationObj = response.attestationObject;

  // Access client JSON
  const clientJSON = response.clientDataJSON;

  // Return authenticator data ArrayBuffer
  const authenticatorData = response.getAuthenticatorData();

  // Return public key ArrayBuffer
  const pk = response.getPublicKey();

  // Return public key algorithm identifier
  const pkAlgo = response.getPublicKeyAlgorithm();

  // Return permissible transports array
  const transports = response.getTransports();
});

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

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

Спецификации

Спецификация
Web Authentication: API для доступа к учетным данным открытого ключа - Уровень 3 # dictionary-makecredentialoptions

Совместимость с браузерами

	Рабочие столы					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на iOS	Samsung Internet	WebView Android
`PublicKeyCredentialCreationOptions`	67	18	60	54	13	70	60	49	13	10.0	Нет
`attestation`	67	18	60	54	13	70	60	49	13	10.0	Нет
`extensions`	67	18	60	54	13	70	60	49	13	10.0	Нет
`requireResidentKey`	89	89	Нет	75	Нет	108	Нет	73	Нет	21.0	Нет
`residentKey`	89	89	114	75	Нет	108	Нет	73	Нет	21.0	Нет

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialCreationOptions