PublicKeyCredentialCreationOptions

安全上下文:此功能仅在安全上下文 (HTTPS) 中可用,在一些或所有支持的浏览器中可用。

PublicKeyCredentialCreationOptions 字典表示传递给 CredentialsContainer.create() 的对象,作为 publicKey 选项的值:也就是说,当使用 create() 通过 Web 身份验证 API 创建公钥凭据时。

实例属性

attestation 可选

一个字符串,指定依赖方对在凭据创建期间如何传递证明语句(即提供身份验证器及其数据的真实性的可验证证据)的偏好。该值可以是以下之一

"none"

指定依赖方对身份验证器证明不感兴趣。这可能是为了避免为向依赖方服务器中继标识信息而进行额外的用户同意,或者避免为一个证明证书颁发机构 (CA) 进行往返,目的是使身份验证过程更顺畅。如果选择 "none" 作为 attestation 值,并且身份验证器发出信号表明它使用 CA 生成其证明语句,则客户端应用程序将用“None”证明语句替换它,表明没有证明语句可用。

"direct"

指定依赖方希望收到身份验证器生成的证明语句。

"enterprise"

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

"indirect"

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

如果省略 attestation,它将默认为 "none"

attestationFormats 可选

一个字符串数组,指定依赖方对身份验证器使用的证明语句格式的偏好。值应按从最高到最低的偏好顺序排列,并应被视为提示——身份验证器可以选择以不同的格式发布证明语句。有关有效格式的列表,请参见 WebAuthn Attestation Statement Format Identifiers

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

authenticatorSelection 可选

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

authenticatorAttachment 可选

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

"platform"

身份验证器是 WebAuthn 运行的设备的一部分(称为平台身份验证器),因此 WebAuthn 将使用该平台可用的传输方式(如平台特定 API)与它通信。绑定到平台身份验证器的公钥凭据称为平台凭据

"cross-platform"

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

如果省略,任何类型的身份验证器(平台或跨平台)都可以被选中用于凭据创建操作。

requireResidentKey 可选

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

如果省略,requireResidentKey 默认为 false

residentKey 可选

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

"discouraged"

依赖方更喜欢创建服务器端凭据,但会接受客户端可发现凭据。

"preferred"

依赖方强烈希望创建客户端可发现凭据,但会接受服务器端凭据。用户代理应引导用户完成设置用户验证(如果需要),以创建可发现凭据。这优先于 userVerification 设置。

"required"

依赖方需要客户端可发现凭据。如果无法创建,则会抛出错误。

如果省略,如果 requireResidentKeytrue,则 residentKey 默认为 "required",否则默认值为 "discouraged"

userVerification 可选

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

"discouraged"

依赖方更喜欢对 create() 操作不进行用户验证,以最大限度地减少对用户体验的影响。

"preferred"

依赖方更喜欢对 create() 操作进行用户验证,但如果无法执行用户验证,它不会失败。

"required"

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

如果省略,userVerification 默认为 "preferred"

challenge

一个由依赖方服务器提供的 ArrayBufferTypedArrayDataView,用作 密码挑战。此值将由身份验证器签名,签名将作为 AuthenticatorAttestationResponse.attestationObject 的一部分发送回来。

excludeCredentials 可选

一个 Array,描述已经映射到此用户帐户(由 user.id 标识)的现有凭据。这是由依赖方提供的,并由用户代理检查,以避免在已经具有映射到指定用户帐户的凭据的身份验证器上创建新的公钥凭据。例如,对于已经拥有某些凭据的现有用户。每个项目都应具有以下形式

id

一个 ArrayBufferTypedArrayDataView,表示现有凭据 ID。

transports 可选

一个 Array,表示允许的传输方式的字符串。可能的传输方式有:"ble""hybrid""internal""nfc""usb"(有关更多详细信息,请参见 getTransports())。

type

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

如果 create() 调用试图在身份验证器上创建重复的公钥凭据,用户代理将引导用户使用不同的身份验证器创建凭据,或者在无法创建的情况下失败。

如果省略 excludeCredentials,它将默认为空数组。

extensions 可选

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

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

pubKeyCredParams

一个指定依赖方支持的密钥类型和签名算法的对象数组,按从最优到最劣的顺序排列。客户端和验证器将尽力创建最优类型的凭据。这些对象将包含以下属性

alg

一个等于COSE 算法标识符的数字,表示用于此凭据类型的加密算法。建议希望支持各种验证器的依赖方至少在提供的选择中包含以下值

  • -8: Ed25519
  • -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 应用程序愿意等待创建操作完成的时间。此提示可能会被浏览器覆盖。

user

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

displayName

一个提供用户友好型用户显示名称的字符串(例如:"John Doe"),此名称将在用户最初与依赖方注册时设置。

id

一个ArrayBufferTypedArrayDataView,表示用户帐户的唯一 ID。此值的长度最大为 64 字节,不打算向用户显示。

name

一个提供用户帐户的用户友好型标识符的字符串,以帮助区分具有相似displayName的不同帐户。这可能是电子邮件地址(例如"[email protected]")、电话号码(例如"+12345678901")或其他类型的用户帐户标识符(例如"johndoe667")。

hints 可选

一个字符串数组,提供关于用户代理应该为用户提供什么身份验证 UI 的提示。

这些值可以是以下任何一种

"security-key"

身份验证需要一个单独的专用物理设备来提供密钥。

"client-device"

用户使用自己的设备(例如手机)进行身份验证。

"hybrid"

身份验证依赖于授权/身份验证方法的组合,可能依赖于用户和服务器端机制。

示例

创建公钥凭据

此示例创建一个PublicKeyCredentialCreationOptions,只指定必需的属性,并为其余属性使用默认值。

然后将对象传递给navigator.credentials.create(),以创建一个新的公钥凭据。

js
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对象,提供对多个有用信息(包括验证器数据、公钥、传输机制等)的访问。

js
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 身份验证:访问公钥凭据的 API - 第 3 级
# dictionary-makecredentialoptions

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。