允許透過相關來源要求,在網站上重複使用密碼金鑰

密碼金鑰會與特定網站連結,只能用於登入建立時所屬的網站。

這項資訊會在仰賴端 ID (RP ID) 中指定,如果是為 example.com 網域建立的密碼金鑰,則可能是 www.example.com 或 example.com。

雖然 RP ID 可防止密碼金鑰做為單一憑證,用於所有地方的驗證,但會造成以下問題:

  • 有多個網域的網站:使用者無法使用同一組密碼金鑰,登入由同一家公司管理的不同國家/地區專屬網域 (例如 example.com 和 example.co.uk)。
  • 品牌網域:使用者無法在單一品牌使用的不同網域 (例如 acme.com 和 acmerewards.com) 之間使用相同憑證。
  • 行動應用程式:行動應用程式通常沒有自己的網域,因此憑證管理較為困難。

雖然有基於身分聯盟和 iframe 的解決方法,但在某些情況下並不方便。相關來源要求提供解決方案。

解決方案

透過相關來源要求,網站可以指定允許使用其 RP ID 的來源。

這樣一來,使用者就能在您經營的多個網站上重複使用相同的密碼金鑰。

如要使用相關來源要求,您必須在特定網址 https://{RP ID}/.well-known/webauthn 提供特殊 JSON 檔案。如果 example.com 想允許其他來源將其用作 RP ID,則應在 https://example.com/.well-known/webauthn: 提供以下檔案

{
  "origins": [
    "https://example.co.uk",
    "https://example.de",
    "https://example-rewards.com"
  ]
}

下次這些網站呼叫建立密碼金鑰 (navigator.credentials.create) 或驗證 (navigator.credentials.get),並使用 example.com 做為 RP ID 時,瀏覽器會發現 RP ID 與要求來源不符。如果瀏覽器支援相關來源要求,會先在 https://{RP ID}/.well-known/webauthn 尋找 webauthn 檔案。如果檔案存在,瀏覽器會檢查提出要求的來源是否位於 allowlist。如果是,則會繼續建立密碼金鑰或進行驗證步驟。

如果瀏覽器不支援相關來源要求,則會擲回 SecurityError。

瀏覽器支援

Chrome 和 Safari 支援相關來源要求。截至 2026 年 1 月,Firefox 仍在考慮是否支援這項功能。您可以在 Mozilla 標準立場問題中追蹤其狀態。

下列示範使用兩個網站:https://ror-1.glitch.me 和 https://ror-2.glitch.me。為了讓使用者能使用同一個密碼金鑰登入這兩個網站,該公司使用相關來源要求,允許 ror-2.glitch.me 使用 ror-1.glitch.me 做為 RP ID。

示範

https://ror-2.glitch.me 實作相關來源要求,使用 ror-1.glitch.me 做為 RP ID,因此 ror-1 和 ror-2 在建立密碼金鑰或進行驗證時,都會使用 ror-1.glitch.me 做為 RP ID。我們也為這些網站導入了共用密碼金鑰資料庫。

請觀察下列使用者體驗:

  • 您可以在 ror-2 上成功建立密碼金鑰,並使用該密碼金鑰進行驗證,即使其 RP ID 為 ror-1 (而非 ror-2)。
  • 在 ror-1 或 ror-2 建立密碼金鑰後,您可以在 ror-1 和 ror-2 上使用該密碼金鑰進行驗證。由於 ror-2 將 ror-1 指定為 RP ID,因此從上述任一網站提出密碼金鑰建立或驗證要求,等同於在 ror-1 上提出要求。RP ID 是唯一將要求與來源連結的項目。
  • 在 ror-1 或 ror-2 建立密碼金鑰後,Chrome 就能在 ror-1 和 ror-2 自動填入密碼金鑰。
  • 在上述任一網站建立的憑證,RP ID 都會是 ror-1。
Chrome 會在兩個網站上自動填入。
有了相關來源要求,使用者就能在 ror-1 和 ror-2 使用相同的密碼金鑰憑證。Chrome 也會自動填入憑證。

查看程式碼:

步驟 1:導入共用帳戶資料庫

如果您希望使用者能使用相同的密碼金鑰登入 site-1 和 site-2,請導入這兩個網站共用的帳戶資料庫。

步驟 2:在 site-1 設定 .well-known/webauthn JSON 檔案

首先,請設定 site-1.com,允許 site-2.com 將其做為 RP ID 使用。方法是建立 WebAuthn JSON 檔案:

{
    "origins": [
        "https://site-2.com"
    ]
}

JSON 物件必須包含名為 origins 的鍵,其值為一或多個字串組成的陣列,其中包含網路來源。

重要限制:最多 5 個標籤

系統會處理這份清單中的每個元素,擷取 eTLD + 1 標籤。舉例來說,example.co.uk 和 example.de 的 eTLD + 1 標籤都是 example。但 example-rewards.com 的 eTLD + 1 標籤是 example-rewards。在 Chrome 中,標籤數量上限為 5 個。

步驟 3:在 site-1 提供 .well-known/webauthn JSON

接著,在 site-1.com/.well-known/webauthn 下提供 JSON 檔案。

例如,在 Express 中:

app.get("/.well-known/webauthn", (req, res) => {
  const origins = {
    origins: ["https://site-2.com"],
  };
  return res.json(origins);
});

這裡我們使用 Express res.json,這項功能已設定正確的 content-type ('application/json');

步驟 4:在 site-2 中指定 RP ID

在 site-2 程式碼集中,視需要將 site-1.com 設為 RP ID:

  • 建立憑證後:
    • 在傳遞至 navigator.credentials.create 前端呼叫的憑證建立 options 中,將 site-1.com 設為 RP ID,通常在伺服器端產生。
    • 將 site-1.com 設為預期的 RP ID,因為您會在將憑證儲存至資料庫前執行憑證驗證。
  • 驗證後:
    • 在傳遞至 navigator.credentials.get 前端呼叫的驗證 options 中,將 site-1.com 設為 RP ID,通常在伺服器端產生。
    • 在驗證使用者前,您會先驗證憑證,因此請將 site-1.com 設為要在伺服器上驗證的預期 RP ID。

疑難排解

Chrome 彈出式視窗顯示錯誤訊息。
建立憑證時,Chrome 顯示的錯誤訊息。如果系統在 `https://{RP ID}/.well-known/webauthn` 找不到 `.well-known/webauthn` 檔案,就會擲回這項錯誤。
Chrome 彈出式視窗顯示錯誤訊息。
建立憑證時,Chrome 顯示的錯誤訊息。如果系統找到 `.well-known/webauthn` 檔案,但檔案未列出您要建立憑證的來源,就會擲回這項錯誤。

其他注意事項

在網站和行動應用程式之間共用密碼金鑰

相關來源要求可讓使用者在多個網站重複使用密碼金鑰。如要讓使用者在網站和行動應用程式中重複使用密碼金鑰,請採用下列技術:

跨網站共用密碼

相關來源要求可讓使用者在不同網站重複使用密碼金鑰。不同密碼管理工具在跨網站共用密碼時,採用的解決方案也不同。 如果是 Google 密碼管理工具,請使用Digital Asset Links 。Safari 則採用不同的系統。

Credential Manager 和使用者代理程式的角色

這超出網站開發人員的職責範圍,但請注意,長期來看,RP ID 不應是使用者代理程式或使用者所用 Credential Manager 中,使用者可見的概念。相反地,使用者代理程式和 Credential Manager 應向使用者顯示憑證的使用位置。這項變更需要一些時間才能實施。暫時的解決方法是同時顯示目前的網站和原始註冊網站。