PublicKeyCredentialCreationOptions

实例属性

attestation 可选

一个字符串，指定依赖方在凭据创建期间如何传达证明声明（即，提供可验证的身份验证器及其数据的真实性证据）的首选项。该值可以是以下之一：

"none"

指定依赖方对身份验证器证明不感兴趣。这可能是为了避免额外的用户同意往返于依赖方服务器以中继识别信息，或往返于证明证书颁发机构（CA），目的是使身份验证过程更顺畅。如果选择 "none" 作为 attestation 值，并且身份验证器表示它使用 CA 生成其证明声明，则客户端应用程序将用“无”证明声明替换它，表示没有可用的证明声明。

"direct"

指定依赖方希望接收身份验证器生成的证明声明。

"enterprise"

指定依赖方希望接收可能包含唯一标识信息的证明声明。这适用于企业内部受控部署，组织希望将注册与特定的身份验证器绑定。

"indirect"

指定依赖方希望接收可验证的证明声明，但它将允许客户端决定如何接收它。例如，客户端可以选择用匿名 CA 生成的证明声明替换身份验证器的断言声明，以保护用户隐私。

如果省略 attestation，则默认为 "none"。

attestationFormats 可选

一个字符串数组，指定依赖方对身份验证器使用的证明声明格式的首选项。值应按偏好从高到低排序，并且应被视为提示 — 身份验证器可以选择以不同格式发布证明声明。有关有效格式的列表，请参阅 WebAuthn 证明声明格式标识符。

如果省略，attestationFormats 默认为空数组。

authenticatorSelection 可选

一个对象，其属性是用于筛选凭据创建操作的潜在身份验证器的条件。此对象可以包含以下属性：

authenticatorAttachment 可选

一个字符串，指示所选身份验证器应允许哪种身份验证器附件类型。可能的值是：

"platform"

身份验证器是 WebAuthn 运行设备的一部分（称为平台身份验证器），因此 WebAuthn 将使用该平台可用的传输与其通信，例如平台特定的 API。绑定到平台身份验证器的公钥凭据称为平台凭据。

"cross-platform"

身份验证器不是 WebAuthn 运行设备的一部分（称为漫游身份验证器，因为它可以在不同设备之间漫游），因此 WebAuthn 将使用跨平台传输协议（例如蓝牙或 NFC）与其通信。绑定到漫游身份验证器的公钥凭据称为漫游凭据。

如果省略，则凭据创建操作可以选择任何类型的身份验证器，无论是平台身份验证器还是跨平台身份验证器。

requireResidentKey 可选

一个布尔值。如果设置为 true，则表示需要驻留密钥（参见 residentKey）。此属性已弃用，但在某些实现中仍可用，以实现与 WebAuthn Level 1 的向后兼容性。如果 residentKey 设置为 "required"，则该值应设置为 true。

如果省略，requireResidentKey 默认为 false。

residentKey 可选

一个字符串，指定依赖方希望创建客户端 可发现凭据 的程度（即，在依赖方不提供凭据 ID 的身份验证请求中可用的凭据 — 调用 navigator.credentials.get() 时 allowCredentials 值为空）。另一种是服务器端凭据，其中依赖方必须在 get() 的 allowCredentials 值中提供凭据 ID。可能的值是：

"discouraged"

依赖方偏好创建服务器端凭据，但将接受客户端可发现凭据。

"preferred"

依赖方强烈偏好创建客户端可发现凭据，但将接受服务器端凭据。如果需要，用户代理应引导用户设置用户验证以创建可发现凭据。这优先于 userVerification 设置。

"required"

依赖方需要客户端可发现凭据。如果无法创建，则会抛出 NotAllowedError DOMException。有关更多详细信息，请参见 create() 异常列表。

如果省略，如果 requireResidentKey 为 true，则 residentKey 默认为 "required"，否则默认值为 "discouraged"。

userVerification 可选

一个字符串，指定依赖方对 create() 操作的用户验证要求。可能的值是：

"discouraged"

为了最大程度地减少对用户体验的干扰，依赖方偏好 create() 操作不进行用户验证。

"preferred"

依赖方偏好 create() 操作进行用户验证，但如果无法执行用户验证，则不会失败。

"required"

依赖方要求 create() 操作进行用户验证 — 如果无法执行用户验证，则会抛出错误。

如果省略，userVerification 默认为 "preferred"。

challenge

由依赖方服务器提供并用作 加密挑战 的 ArrayBuffer、TypedArray 或 DataView。该值将由身份验证器签名，并且签名将作为 AuthenticatorAttestationResponse.attestationObject 的一部分发送回来。

excludeCredentials 可选

一个 Array 对象数组，描述已映射到此用户帐户（由 user.id 标识）的现有凭据。这由依赖方提供，并由用户代理检查，以避免在已将凭据映射到指定用户帐户的身份验证器上创建新的公钥凭据。每个项目应采用以下形式：

id

表示现有凭据 ID 的 ArrayBuffer、TypedArray 或 DataView。

transports 可选

一个 Array 字符串数组，表示允许的传输。可能的传输有："ble"、"hybrid"、"internal"、"nfc" 和 "usb"（有关更多详细信息，请参见 getTransports()）。

type

一个字符串，定义要创建的公钥凭据的类型。目前只能取一个值 "public-key"，但将来可能会添加更多值。

如果 create() 调用试图在身份验证器上创建重复的公钥凭据，用户代理将引导用户使用不同的身份验证器创建凭据，如果不可能，则会失败。

如果省略 excludeCredentials，则默认为空数组。

extensions 可选

一个对象，其中包含表示任何请求扩展的输入值的属性。这些扩展用于在凭据创建过程中由客户端或身份验证器进行特定的额外处理。示例包括指定返回的凭据是否可发现，或者依赖方是否能够存储与凭据关联的大型 blob 数据。

扩展是可选的，不同的浏览器可能会识别不同的扩展。处理扩展对于客户端来说始终是可选的：如果浏览器不识别给定的扩展，它将忽略它。有关使用扩展以及哪些浏览器支持哪些扩展的信息，请参见 Web 身份验证扩展。

hints 可选 实验性

一个字符串数组，提供关于浏览器应为用户提供哪些 UI 以创建公钥凭据的提示。

字符串可以是以下任何一个：

"security-key"

UI 应建议使用单独的物理安全密钥（例如 YubiKey）来创建凭据。

"client-device"

UI 应建议使用与访问 RP 客户端的同一设备上可用的身份验证器来创建凭据。它类似于 authenticatorAttachment platform 值。

"hybrid"

UI 应建议使用通用身份验证器，例如基于智能手机的身份验证器应用程序，来创建凭据。这有利于采用跨设备方法处理身份验证，例如依赖笔记本电脑和智能手机的组合。

authenticatorAttachment cross-platform 值本质上是 hints 选项 security-key 和 hybrid 值的组合 — 如果设备没有蓝牙并且 RP 指定 attachment: "cross-platform"，则生成的 UI 可能与 hints: "security-key" UI 类似。

当数组中包含多个字符串时，它们的顺序表示偏好顺序，从高到低。支持并遵循提示的浏览器应使用它们理解的第一个提示。

hints 选项提供了比 authenticatorAttachment 选项更灵活的方式来指定创建凭据的 UI 偏好，后者完全隐藏了未选择的选项。hints 还允许指示对安全密钥或混合的偏好，这在 authenticatorAttachment 中是不可能做到的。

指定的 hints 可能与 authenticatorAttachment 选项中提供的提示相矛盾。当提供的 hints 与此选项相矛盾时，hints 优先。在特定情况下，浏览器也可能忽略 hints，例如，如果提示的身份验证器类型在用户的设备上不可用。

有关一些具体的代码和 UI 示例，请参见 Chrome 中 WebAuthn 的提示、相关来源请求和 JSON 序列化介绍。

pubKeyCredParams

一个 Array 对象数组，指定依赖方支持的密钥类型和签名算法，按偏好从高到低排序。客户端和身份验证器将尽最大努力创建最偏好类型的凭据。这些对象将包含以下属性：

alg

一个数字，等于 COSE 算法标识符，表示此凭据类型要使用的加密算法。建议希望支持广泛身份验证器的依赖方在提供的选项中至少包含以下值：

• -8: EdDSA
• -7: ES256
• -257: RS256

type

一个字符串，定义要创建的公钥凭据的类型。目前只能取一个值 "public-key"，但将来可能会添加更多值。

如果无法创建列出的任何凭据类型，则 create() 操作失败。

rp

一个对象，描述请求凭据创建的依赖方。它可以包含以下属性：

id 可选

一个字符串，表示依赖方的 ID。公钥凭据只能用于与注册它的同一个依赖方（在 navigator.credentials.get() 调用中由 publicKey.rpId 标识）进行身份验证 — ID 需要匹配。

id 不能包含端口或方案，如标准来源，但域方案必须是 https 方案。id 需要等于来源的有效域，或其域后缀。因此，例如，如果依赖方的来源是 https://login.example.com:1337，则以下 id 是有效的：

• login.example.com
• example.com

但不是：

• m.login.example.com
• com

如果省略，id 默认为文档来源 — 在上述示例中为 login.example.com。

name

一个字符串，表示依赖方的名称（例如，"Facebook"）。这是用户在创建或验证 WebAuthn 操作时将看到的名称。

timeout 可选

一个数值提示，以毫秒为单位，表示调用 Web 应用程序愿意等待创建操作完成的时间。此提示可能会被浏览器覆盖。

用户

一个对象，描述为其生成凭据的用户帐户。它可以包含以下属性：

displayName

一个字符串，提供人类友好的用户显示名称（例如："Maria Sanchez"），该名称将在用户首次注册依赖方时设置。

id

一个 ArrayBuffer、TypedArray 或 DataView，表示用户帐户的唯一 ID。此值的最大长度为 64 字节，不打算向用户显示。

name

一个字符串，提供用户帐户的人类友好标识符，以帮助区分具有相似 displayName 的不同帐户。这可以是电子邮件地址（例如 "elaina.sanchez@example.com"）、电话号码（例如 "+12345678901"）或某种其他类型的用户帐户标识符（例如 "ElainaSanchez667"）。

示例

创建公钥凭据

此示例创建一个 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() 调用返回一个 Promise，该 Promise 将解析为 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();
});

其中一些数据需要存储在服务器上，以用于将来针对此凭据的身份验证操作 — 例如公钥、使用的算法和允许的传输。

有关整体流程如何工作的更多信息，请参见 创建密钥对并注册用户。

规范

浏览器兼容性