PublicKeyCredential:signalUnknownCredential() 靜態方法

可用性有限

此特性不是基線特性,因為它在一些最廣泛使用的瀏覽器中不起作用。

安全上下文: 此功能僅在安全上下文(HTTPS)中可用,且支援此功能的瀏覽器數量有限。

PublicKeyCredential 介面的 signalUnknownCredential() 靜態方法會告知認證器,憑證 ID 未被 信賴方 (RP) 伺服器識別。

這允許認證器刪除 RP 不允許的憑證,例如已刪除帳戶的憑證,或者在認證器上建立和儲存但未在伺服器上正確更新的帳戶的憑證。通常,在登入因 RP 無法獲取帳戶詳細資訊而失敗後會呼叫此方法。即使當前使用者未透過身份驗證,也可以使用它,因為它不會暴露敏感資訊。

語法

js
signalUnknownCredential(options)

引數

options

一個代表未知憑證的物件,其中包含以下屬性:

credentialId

一個 base64url 編碼的字串,表示未被識別的憑證 ID

rpId

一個字串,表示傳送訊號的 RP 的 ID

返回值

一個 Promise,解析為 undefined

異常

Promise 會因以下異常而拒絕

SecurityError DOMException

RP 域無效。

TypeError DOMException

credentialId 不是有效的 base64url 編碼字串。

描述

使用者認證器中儲存的關於可發現憑證(例如,passkey)的資訊可能與 RP 伺服器不同步。這通常發生在使用者從 RP Web 應用中刪除憑證但未更新認證器時。

當用戶嘗試使用可發現憑證登入時,系統會向用戶顯示認證器中的一組憑證供其選擇,然後將選定的憑證返回給 RP Web 應用以進行登入。如果使用者選擇了一個已從 RP 伺服器刪除的憑證,則該憑證不會被識別,登入也會失敗。這會給使用者帶來困惑的體驗,因為他們期望只看到應該成功的憑證。

為了緩解這個問題,每次基於可發現憑證的登入失敗時,都應該在 RP Web 應用上呼叫 signalUnknownCredential(),以告知認證器該憑證 ID 未被識別。

認證器如何處理此資訊由其自行決定,但期望的做法是刪除相關憑證,以避免認證器和信賴方之間儲存的資料不匹配。

此外,如果 Web 應用能夠在認證器上建立可發現憑證,但由於任何原因無法將憑證資訊上傳到伺服器,也可能呼叫 signalUnknownCredential()

signalUnknownCredential() 可以在當前使用者未透過身份驗證時呼叫,因為它不會暴露敏感資訊。

示例

通知未知憑證

在此示例中,透過 get() 呼叫嘗試使用可發現憑證進行登入。憑證成功返回,憑證 ID 和負載儲存在常量中。

透過 fetch() 請求將負載傳送到 RP 伺服器以登入使用者,但由於 RP 不識別該使用者(例如,因為該憑證先前已從 RP 刪除),請求失敗並返回 404 響應。

因此,我們呼叫 signalUnknownCredential() 方法,並將 rpId 和憑證 ID 傳遞給它,以告知認證器該憑證是 RP 未知的。然後,認證器應該刪除該憑證,以免再次引起相同的問題。

js
const credential = await navigator.credentials.get({
  challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* … */]),
  rpId: "example.com",
  allowCredentials: [],
  // Empty allowCredentials list means only discoverable
  // credentials are presented to the user
});

// Retrieve base64url-encoded credential ID,
// such as "vI0qOggiE3OT01ZRWBYz5l4MEgU0c7PmAA"
const credID = credential.id;
// Retrieve payload to send to the RP server
const payload = credential.toJSON();

const result = await fetch("/login", {
  // fetch() options, will include the payload in the request body
});

// Detect authentication failure due to lack of the credential
if (result.status === 404) {
  if (PublicKeyCredential.signalUnknownCredential) {
    await PublicKeyCredential.signalUnknownCredential({
      rpId: "example.com",
      credentialId: credID,
    });
  } else {
    // Encourage the user to delete the credential from the authenticator
  }
}

規範

規範
Web Authentication:訪問公鑰憑證的 API - 第 3 級
# dom-publickeycredential-signalunknowncredential

瀏覽器相容性

另見