為無密碼登入建立密碼金鑰

密碼金鑰可讓使用者提升使用者帳戶的安全性、操作便利性和便利性。

Eiji Kitamura

使用密碼金鑰而非密碼是網站的絕佳方式，能為網站提供更安全、更簡單、更易於使用及無密碼的使用者帳戶。有了密碼金鑰，使用者就能透過指紋、臉孔或裝置 PIN 碼登入網站或應用程式。

注意： 如要瞭解密碼金鑰的基本概念，請先參閱「使用密碼金鑰登入無密碼」一文。

您必須先建立密碼金鑰、與使用者帳戶建立關聯，並將密碼金鑰儲存在伺服器上，使用者才能使用密碼金鑰登入。

運作方式

在下列情況下，系統可能會要求使用者建立密碼金鑰：

• 使用者使用密碼登入時。
• 當使用者透過其他裝置的密碼金鑰登入 (即 authenticatorAttachment 為 cross-platform) 時。
• 使用者可以透過專屬頁面管理密碼金鑰。

如要建立密碼金鑰，請使用 WebAuthn API。

密碼金鑰註冊流程的四個元件如下：

• 後端：您的後端伺服器，保留帳戶資料庫儲存公開金鑰和其他中繼資料。
• 前端：與瀏覽器通訊，並將擷取要求傳送至後端的前端。
• 瀏覽器：執行 JavaScript 的使用者瀏覽器。
• Authenticator：用來建立及儲存密碼金鑰的使用者驗證器。這可能包括在瀏覽器所用裝置 (例如使用 Windows Hello) 或其他裝置 (例如手機) 上的密碼管理工具。

將密碼金鑰新增至現有使用者帳戶的流程如下：

1. 使用者登入網站。
2. 使用者登入後，會要求在前端建立密碼金鑰，例如按下「建立密碼金鑰」按鈕。
3. 前端會從後端要求資訊以建立密碼金鑰，例如使用者資訊、驗證問題和要排除的憑證 ID。
4. 前端呼叫 navigator.credentials.create() 以建立密碼金鑰。這個呼叫會傳回承諾值。
5. 當使用者使用裝置的螢幕鎖定功能表示同意後，系統就會建立密碼金鑰。系統已解析承諾，並將公開金鑰憑證傳回前端。
6. 前端將公開金鑰憑證傳送至後端，並儲存憑證 ID 和與使用者帳戶相關聯的公開金鑰，供日後的驗證使用。

相容性

大部分瀏覽器都支援 WebAuthn，但有些微差異。請參閱「裝置支援 - passwordss.dev」，瞭解哪些類型的瀏覽器和作業系統支援建立密碼金鑰。

建立新的密碼金鑰

以下說明如何在要求建立新密碼金鑰時，前端運作。

特徵偵測

顯示「建立新的密碼金鑰」按鈕前，請先確認下列事項：

• 瀏覽器透過 PublicKeyCredential 支援 WebAuthn。

瀏覽器支援

• 67
• 18
• 60
• 13

來源

• 裝置使用 PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() 支援平台驗證器 (可以建立密碼金鑰並使用密碼金鑰進行驗證)。

瀏覽器支援

• 67
• 18
• 60
• 13

來源

• 瀏覽器透過 PublicKeyCredenital.isConditionalMediationAvailable() 支援 WebAuthn 條件式 UI。

瀏覽器支援

• 108
• 108
• 119
• 16

來源

// Availability of `window.PublicKeyCredential` means WebAuthn is usable.  
// `isUserVerifyingPlatformAuthenticatorAvailable` means the feature detection is usable.  
// `​​isConditionalMediationAvailable` means the feature detection is usable.  
if (window.PublicKeyCredential &&  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable &&  
    PublicKeyCredential.​​isConditionalMediationAvailable) {  
  // Check if user verifying platform authenticator is available.  
  Promise.all([  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(),  
    PublicKeyCredential.​​isConditionalMediationAvailable(),  
  ]).then(results => {  
    if (results.every(r => r === true)) {  
      // Display "Create a new passkey" button  
    }  
  });  
}  

在符合所有條件前，這個瀏覽器將不支援密碼金鑰。在這之前，系統才會顯示「建立新的密碼金鑰」按鈕。

從後端擷取重要資訊

在使用者點選按鈕時，擷取重要資訊，從後端呼叫 navigator.credentials.create()：

• challenge：在 ArrayBuffer 中針對這項註冊作業產生的伺服器產生的驗證問題。這是必要項目，但除非進行認證，否則未在註冊期間使用。請注意，本文未提及的進階主題。
• user.id：使用者的專屬 ID。這個值必須為 ArrayBuffer，其中不包含個人識別資訊，例如電子郵件地址或使用者名稱。每個帳戶產生的 16 位元組隨機值通常很好。
• user.name：這個欄位應保留使用者可識別的帳戶專屬 ID，例如電子郵件地址或使用者名稱。這會顯示在帳戶選取器中。(如果使用使用者名稱，請使用與密碼驗證相同的值)。
• user.displayName：這個欄位為必填欄位，可讓使用者更容易理解。這個名稱可以重複，可以是使用者選擇的名稱。如果您的網站沒有可加入的合適值，請傳送空字串。視瀏覽器而定，帳戶選取器可能會顯示這項資訊。
• excludeCredentials：提供已註冊的憑證 ID 清單，防止註冊同一部裝置。transports 成員 (如有提供) 應包含在每個憑證註冊期間呼叫 getTransports() 的結果。

注意： 從伺服器轉移的 ArrayBuffer 值 (例如 challenge、user.id 和 excludeCredentials 的憑證 id) 必須進行傳輸編碼。別忘了先在前端解碼，再傳遞至 WebAuthn API 呼叫。建議您使用 Base64URL 編碼。

呼叫 WebAuthn API 以建立密碼金鑰

請呼叫 navigator.credentials.create() 以建立新的密碼金鑰。API 會傳回承諾，等待使用者與顯示強制回應對話方塊的互動。

瀏覽器支援

• 60
• 18
• 60
• 13

來源

const publicKeyCredentialCreationOptions = {
  challenge: *****,
  rp: {
    name: "Example",
    id: "example.com",
  },
  user: {
    id: *****,
    name: "john78",
    displayName: "John",
  },
  pubKeyCredParams: [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}],
  excludeCredentials: [{
    id: *****,
    type: 'public-key',
    transports: ['internal'],
  }],
  authenticatorSelection: {
    authenticatorAttachment: "platform",
    requireResidentKey: true,
  }
};

const credential = await navigator.credentials.create({
  publicKey: publicKeyCredentialCreationOptions
});

// Encode and send the credential to the server for verification.  

上述未說明的參數如下：

• rp.id：RP ID 是網域，網站可以指定網域或可註冊的後置字串。舉例來說，如果 RP 來源為 https://login.example.com:1337，則 RP ID 可以是 login.example.com 或 example.com。如果將 RP ID 指定為 example.com，使用者即可在 login.example.com 或 example.com 的任何子網域上進行驗證。

• rp.name：RP 的名稱。

• pubKeyCredParams：這個欄位會指定 RP 支援的公開金鑰演算法。建議您將其設為 [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}]。這會指定對使用 P-256 和 RSA PKCS#1 的 ECDSA 提供支援，並支援這些 ECDSA。

• authenticatorSelection.authenticatorAttachment：如果這個密碼金鑰的建立程序是密碼升級 (例如登入後的促銷活動)，請將其設為 "platform"。"platform" 表示 RP 需要的平台驗證器 (內嵌於平台裝置的驗證器)，因此不會提示插入 USB 安全金鑰等。使用者可以選擇較簡單的建立密碼金鑰。

  注意： 如果使用者是從設定頁面建立新的密碼金鑰，請勿設定這個參數。透過設定頁面建立密碼金鑰可能是進階使用者，因此他們能靈活使用漫遊驗證器，例如安全金鑰。

• authenticatorSelection.requireResidentKey：將其設為布林值「true」。可搜尋的憑證 (常駐金鑰) 會將使用者資訊儲存至密碼金鑰，讓使用者在驗證時選取帳戶。如要進一步瞭解可搜尋的憑證，請參閱「可搜尋的憑證深入說明」一文

• authenticatorSelection.userVerification：指出使用裝置螢幕鎖定功能進行使用者的驗證是 "required"、"preferred" 或 "discouraged"。預設值為 "preferred"，表示驗證器可能會略過使用者驗證。請將這個屬性設為 "preferred" 或省略屬性。

  注意： 如果要求 userVerification 設為 "preferred"，驗證者可能會略過使用者驗證檢查。舉例來說，如果裝置沒有任何生物特徵辨識感應器，、使用者尚未設定裝置 (沒有註冊指紋)，或是感應器暫時無法使用 (蓋上螢幕蓋子時在筆記型電腦上執行)。回應驗證器資料中的 UV 位元一律會指出是否已執行使用者驗證。如要確保這是雙重驗證，請在 UV 位元為「關閉」時要求第二個步驟 (例如密碼)。或者，您也可以將 userVerification 設為 "required"。如要進一步瞭解此案件，請參閱「userVerification 深入介紹」。

注意： 有些瀏覽器不需要 authenticatorSelection 上的任何參數就能建立密碼金鑰，但有些瀏覽器可能需要明確指定。

將傳回的公開金鑰憑證傳送至後端

使用者透過裝置的螢幕鎖定功能表示同意後，系統就會建立密碼金鑰，並將 PublicKeyCredential 物件傳回至前端。

承諾產品可能會基於各種原因遭拒。您可以檢查 Error 物件的 name 屬性來處理這些錯誤：

• InvalidStateError：裝置上已有密碼金鑰。系統不會向使用者顯示錯誤對話方塊，且網站不應將此視為錯誤，也就是使用者希望註冊本機裝置且發生了這個錯誤。
• NotAllowedError：使用者已取消作業。
• 其他例外狀況：發生非預期的狀況。瀏覽器會向使用者顯示錯誤對話方塊。

公開金鑰憑證物件包含下列屬性：

• id：已建立密碼金鑰的 Base64URL 編碼 ID。這個 ID 可協助瀏覽器判斷進行驗證後，裝置中是否有相符的密碼金鑰。這個值需要儲存在後端的資料庫中。
• rawId：憑證 ID 的 ArrayBuffer 版本。
• response.clientDataJSON：ArrayBuffer 編碼的客戶資料。
• response.attestationObject：ArrayBuffer 編碼的認證物件。其中包含 RP ID、旗標和公開金鑰等重要資訊。
• authenticatorAttachment：在支援密碼金鑰的裝置上建立這個憑證時，傳回 "platform"。
• type：這個欄位一律設為 "public-key"。

若您使用程式庫在後端處理公開金鑰憑證物件，建議您先使用 base64url 進行部分編碼，再將整個物件傳送至後端。

注意： 視需要提供憑證的 response 成員 (AuthenticatorAttestationResponse)，提供 getTransports()、getPublicKey()、getAuthenticatorData() 和 getPublicKeyAlgorithm() 函式以擷取憑證元素。

儲存憑證

在後端收到公開金鑰憑證後，將憑證傳送給 FIDO 程式庫來處理物件。

注意： 建議您使用伺服器端程式庫或解決方案，而不要自行編寫程式碼來處理公開金鑰憑證。查看開放原始碼程式庫，瞭解如何處理公開金鑰憑證。

接著，您可以將從憑證擷取的資訊儲存到資料庫，以供日後使用。下列清單包含一些可以儲存的一般屬性：

• 憑證 ID (主金鑰)
• 使用者 ID
• 公開金鑰

公開金鑰憑證也包括了您可能會想在資料庫中儲存的下列資訊：

• 備份資格標記：true (如果裝置符合密碼金鑰同步處理的資格)。
• 備份狀態標記：如果已建立的密碼金鑰實際上設為同步處理，則為 true。
• 傳輸：裝置支援的傳輸清單："internal" 表示裝置支援密碼金鑰，"hybrid" 表示裝置也支援另一部裝置上的驗證作業。

如需詳細操作說明，請參閱「伺服器端密碼金鑰註冊」一文

如要驗證使用者，請參閱「透過表單自動填入功能使用密碼金鑰登入」。

資源

• 伺服器端密碼金鑰註冊
• 透過表單自動填入功能使用密碼金鑰登入
• 密碼金鑰
• Apple 文件：透過網路服務驗證使用者
• Google 文件：使用密碼金鑰進行無密碼登入