使用 RP ID 在多个网域和应用中管理通行密钥

Eiji Kitamura

在 WebAuthn 和通行密钥中，依赖方 ID (RP ID) 通过域名指定凭据的作用范围。创建通行密钥时，浏览器会将其与特定的 RP ID 相关联。然后，浏览器会阻止在与该 ID 不匹配或不在该 ID 范围内的网域上使用该通行密钥。正确定义 RP ID 可确保在子网域、跨网站来源和第一方移动应用中获得顺畅的通行密钥体验。

RP 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 示例，具体取决于您的来源主机：

来源主机 允许的 RP 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。更具体的 RP ID（例如 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，并在所有网站上使用该 ID。
  • 托管配置文件：主 RP ID 网域必须在 /.well-known/webauthn 托管一个列出授权来源的配置文件。
  • 保持一致性：即使在用户使用 https://www.example.co.jp 的情况下，WebAuthn 调用中的 rpId 也必须是主要账号（例如 example.com），无论是在创建时还是在身份验证时。

RP 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（托管在 https://example.com/.well-known/assetlinks.json）的 DAL 示例

[
  {
    "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 开发者文档中的使用通行密钥连接到服务。

摘要

RP ID 决定了用户在何处访问通行密钥。在实施时，请注意以下几点：

  • 层次结构和子网域：RP ID 必须是网域字符串（eTLD+1 或更高级别）。使用更广泛的网域（例如 example.com）可让通行密钥在所有子网域（例如 login.example.com 和 shop.example.com）中发挥作用。
  • 跨网站解决方案：对于跨多个 eTLD+1 的服务，请使用相关来源请求 (ROR)。这需要一个 RP ID 和一个位于 /.well-known/webauthn 的配置文件。
  • 移动集成：使用 Digital Asset Links (DAL) 文件（位于 /.well-known/assetlinks.json，适用于 Android）和 apple-app-site-association (AASA) 文件（位于 /.well-known/apple-app-site-association，适用于 iOS）在您的网站与移动应用之间建立经过验证的关系。

了解详情