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();
});

其中一些資料需要儲存在伺服器上，以用於將來針對此憑據的身份驗證操作 — 例如公鑰、使用的演算法和允許的傳輸。

有關整體流程如何工作的更多資訊，請參見 建立金鑰對並註冊使用者。

規範

瀏覽器相容性