使用 RP ID 管理多個網域和應用程式的密碼金鑰

Eiji Kitamura

在 WebAuthn 和密碼金鑰中，憑證的信賴平台 ID (RP ID) 會依網域名稱指定憑證範圍。建立密碼金鑰時，瀏覽器會將密碼金鑰與特定 RP ID 繫結。瀏覽器隨後會禁止在不符或超出該 ID 範圍的網域上使用該密碼金鑰。正確定義 RP ID 可確保子網域、跨網站來源和第一方行動應用程式提供順暢的密碼金鑰體驗。

受限方 ID 基本知識

憑證管理機構 ID (RP ID) 是用來識別服務或網站的專屬字串。RP ID 必須是網域字串。可以是目前的確切主機名稱，也可以是範圍較廣的上層網域，但必須是 eTLD+1 或更高。您無法使用 IP 位址和公用尾碼 (eTLD) 做為 RP ID。

舉例來說，如果您在 https://www.example.com 代管伺服器，可以視具體需求使用 example.com 或 www.example.com 做為 RP ID。下表根據來源主機，列出允許的 RP ID 範例：

來源主機 允許的受限方 ID (eTLD+1)
https://login.example.com example.com 或 login.example.com
https://example.com:8080 example.com (不含轉移號碼)
https://mobile.example.co.jp example.co.jp 或 mobile.example.co.jp
https://sub.project.org.uk project.org.uk 或 sub.project.org.uk
https://user.github.io user.github.io (github.io 是 eTLD)
https://myapp.pages.dev myapp.pages.dev (pages.dev 是 eTLD)
http://localhost localhost (HTTPS 規定的例外情況)

建立密碼金鑰時，瀏覽器會以密碼編譯方式將密碼金鑰與 RP ID 繫結。如要使用憑證，驗證要求的來源必須與該 RP ID 相符。

使用 eTLD+1 做為 RP ID 時，密碼金鑰可在相關子網域中運作。舉例來說，RP ID example.com 適用於 https://login.example.com 和 https://shop.example.com。較具體的 RPID (例如 login.example.com) 適用於確切來源，但不適用於 https://shop.example.com。

跨網站環境中的 RP ID

如果服務涵蓋多個 eTLD+1 (例如 example.com 和 example.co.jp)，就是跨網站設定。標準 RP ID 不支援跨網站設定。

如要在不同網站之間共用密碼金鑰，請使用相關來源要求 (ROR)。ROR 可讓您在不同網站之間共用密碼金鑰，因為用戶端 (瀏覽器) 會將不同來源視為同一邏輯服務的一部分。

ROR 規定：

  • 選擇一個 RP ID：您必須選擇一個 RP ID，並在所有網站上使用。
  • 代管設定檔：主要 RP ID 網域必須在 /.well-known/webauthn 代管設定檔，列出授權來源。
  • 保持一致：即使使用者位於 https://www.example.co.jp，WebAuthn 呼叫中的 rpId 仍必須是主要項目 (例如 example.com)，無論是建立或驗證時皆然。

受限方 ID example.com 的 ROR 範例：https://example.com/.well-known/webauthn

{
  "origins": [
    "https://www.example.co.jp",
    "https://shop.example"
  ]
}

如要進一步瞭解相關來源要求實作詳細資料，請參閱「使用相關來源要求，在網站間重複使用密碼金鑰」

行動應用程式中的 RP ID

行動應用程式可以與網域建立關聯，藉此使用密碼金鑰。您必須在伺服器上代管驗證檔案，才能建立這項關係。

Android Credential Manager 需要 RP ID 網域上的 Digital Asset Link (DAL) 檔案，才能與應用程式建立關聯。

  • 代管：在 https://<RP ID>/.well-known/assetlinks.json 代管檔案。
  • 驗證：驗證 clientDataJSON 中的 origin。如果是 Android，這會是 android:apk-key-hash:<hash> 等字串。

RP ID example.com 的 DAL 範例 (託管於 https://example.com/.well-known/assetlinks.json)

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.google.credentialmanager.sample",
      "sha256_cert_fingerprints": [
        "4F:20:47:1F:D9:9A:BA:96:47:8D:59:27:C2:C8:A6:EA:8E:D2:8D:14:C0:B6:A2:39:99:9F:A3:4D:47:3D:FA:11"
      ]
    }
  }
]

詳情請參閱「設定應用程式與網站之間的 Digital Asset Links」。

iOS：關聯網域

Apple 平台需要在 RP ID 網域上提供 apple-app-site-association (AASA) 檔案，才能與應用程式建立關聯。

  • AASA 檔案：主機 https://<RP_ID>/.well-known/apple-app-site-association。
  • 權利：在應用程式權利中新增 webcredentials:<app info>。

RP ID example.com 的 AASA 範例： https://example.com/.well-known/apple-app-site-association：

{
  "webcredentials":
    {
      "apps": ["EXAMPLE123.com.example.passkey"]
    }
}

詳情請參閱 Apple 開發人員說明文件中的「Connecting to a service with passkeys」(使用密碼金鑰連線至服務)。

摘要

RP ID 會決定使用者存取密碼金鑰的位置。導入時請注意下列事項：

  • 階層和子網域：RP ID 必須是網域字串 (eTLD+1 或更高)。使用較廣泛的網域 (例如 example.com) 可讓密碼金鑰在所有子網域 (例如 login.example.com 和 shop.example.com) 中運作。
  • 跨網站解決方案：針對涵蓋多個 eTLD+1 的服務，使用相關來源要求 (ROR)。這需要一個 RP ID 和設定檔，位於 /.well-known/webauthn。
  • 行動整合：使用 Android 的 /.well-known/assetlinks.json Digital Asset Links (DAL) 檔案，以及 iOS 的 /.well-known/apple-app-site-association apple-app-site-association (AASA) 檔案，在網站和行動應用程式之間建立經過驗證的關係。

瞭解詳情