允许通过相关源请求在您的各个网站上重复使用通行密钥

Maud Nalpas

相关源请求解决的问题

通行密钥与特定的网站相关联，只能用于在为其创建的网站进行登录。

这是由依赖方 ID (RP ID)，对于为 example.com 网域创建的通行密钥，它可以是 www.example.com 或 example.com。

而 RP ID 可防止将通行密钥用作 随时随地进行身份验证，会给以下方面带来问题：

• 拥有多个域名的网站：用户无法使用相同的通行密钥 跨国家/地区特定的网域（例如 example.com 和 example.co.uk）。
• 品牌网域：用户无法针对各个网域使用相同的凭据 同一品牌使用的不同网域（例如 acme.com 和 acmerewards.com）。
• 移动应用：移动应用通常没有自己的网域，因此 凭据管理颇具挑战性。

有一些基于身份联合的解决方法，还有一些基于身份联合的解决方法 但在某些情况下使用起来很不方便。相关源请求优惠 解决方案。

注意 ：RP ID 会在不同网站之间分割凭据，但钓鱼式攻击是 保护措施实际上是通过在 CollectedClientData 字段中验证网站的来源。

解决方案

包含 相关源请求、 网站可以指定允许使用其 RP ID 的来源。

这样一来，用户便有可能在您运营的多个网站上重复使用相同的通行密钥。

要使用相关源请求，您需要在 特定网址 https://{RP ID}/.well-known/webauthn。如果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， 与发出请求的来源不匹配。如果浏览器支持 Related Origin 请求，它首先查找 位于 https://{RP ID}/.well-known/webauthn 的 webauthn 文件。如果文件存在 浏览器会检查发出请求的来源是否 文件。如果是，它会继续执行通行密钥创建或身份验证步骤。 如果浏览器不支持相关源请求，则会抛出 SecurityError。

浏览器支持

• Chrome：从 Chrome 开始支持 128。
• Safari：从 macOS 15 Beta 3 开始支持，在移动设备的 iOS 18 Beta 3 中也受支持。
• Firefox： 等待位置。

。

警告 ：自 2024 年 8 月起，Firefox 不再支持相关源请求，并且 getClientCapabilities 检测缺少的功能并实现 后备广告。如果您实施“Related Origin Request”（相关源请求），Firefox 用户将无法创建 在打算使用其他网站的网域中，设置通行密钥（或使用通行密钥登录） 系统会抛出 RP ID 和 SecurityError。

如何设置相关源请求

以下演示使用 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。

。 <ph type="x-smartling-placeholder">

</ph>

借助相关源请求，用户可以在 ror-1 和 ror-2 中使用相同的通行密钥凭据。Chrome 还会自动填充凭据。

查看代码：

• 请参阅 ror-1 代码库中设置的 ./well-known/webauthn 文件。
• 请参阅 ror-2 代码库中的 RP_ID_ROR 出现次数。

。

注意： 为简单起见，此演示版实际上不会在后台进行任何密码检查。本演示将重点介绍通行密钥。

第 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”的键，其值为 1 的数组 或更多包含网络源的字符串。

重要限制：最多 5 个标签

系统会处理此列表中的每个元素，以提取 eTLD + 1 个标签。 例如，example.co.uk 和 example.de 的 eTLD + 1 标签 example。但 example-rewards.com 的 eTLD + 1 标签为 example-rewards。 Chrome 中的标签数量上限为 5 个。

警告 ：如果列表包含的标签过多（超过 5 个），则说明 元素将被忽略。

第 3 步：在 site-1 中提供 .well-known/webauthn JSON

然后，在 site-1.com/.well-known/webauthn 下提供 JSON 文件。

注意 ：该文件必须采用 application/json 内容类型提供，并且包含 列出单个 JSON 对象 允许的来源。该文件的正确格式为：/.well-known/webauthn（不包含 .json 扩展名）。

例如，简而言之：

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：

• 创建凭据时： <ph type="x-smartling-placeholder">
  </ph>
  • 在创建凭据时将 site-1.com 设置为 RP ID 传递给 navigator.credentials.create 的 options 前端调用，通常在服务器端生成。
  • 在运行凭据时，将 site-1.com 设置为预期的 RP ID 然后再将其保存到数据库。
• 在进行身份验证时： <ph type="x-smartling-placeholder">
  </ph>
  • 将 site-1.com 设置为身份验证 options 中的 RP ID 传递给 navigator.credentials.get 前端调用；以及 通常是在服务器端生成的
  • 将 site-1.com 设置为要在 因此您在验证用户身份之前需要运行凭据验证。

。

注意： origin 会怎么样？RP name 是多少？在 site-2 代码库中，预期的 origin 应保持不变 (https://site-2.com)，因为它指定了请求应在何处 来源。根据 RP 名称 (rp.name)，它实际上并没有使用。您可以将其留空。

问题排查

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 创建凭据时 Chrome 中会显示错误消息。如果在 `https://{RP ID}/.well-known/webauthn` 中找不到您的 `.well-known/webauthn` 文件，则会抛出此错误。

。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 创建凭据时 Chrome 中会显示错误消息。如果可以找到您的 `.well-known/webauthn` 文件，但其中未列出您要尝试创建凭据的来源，就会抛出此错误。

其他注意事项

在网站和移动应用之间共享通行密钥

借助相关源请求，您的用户可以在多个 网站。 若要允许用户在网站和移动应用中重复使用通行密钥，请按以下步骤操作： 使用以下技巧：

• 在 Chrome 中：Digital Asset 链接。如需了解详情，请访问： 添加对 Digital Asset Links 的支持。
• 在 Safari 中： 关联的网域。

跨网站共享密码

相关源请求可让您的用户跨网站重复使用通行密钥。 跨网站共享密码的解决方案因密码管理工具而异。 对于 Google 密码管理工具，请使用 Digital Asset Links 。 Safari 使用的是其他系统。

凭据管理器和用户代理的角色

这超出了您作为网站开发者的职责范围，但请注意， 术语，RP ID 不应是用户代理或 凭据管理器。用户代理和凭据 管理员应向用户显示使用其凭据的位置。此更改 需要一些时间来实现。临时解决方法是同时显示 当前网站和原始注册网站。