了解 WebAuthn 关联源请求如何让 Passkey 跨多个域使用。内附完整实现指南和真实世界案例。

Vincent
Created: October 31, 2025
Updated: October 31, 2025

See the original blog version in English here.
Passkey 是安全、用户友好型身份验证的新标准。它建立在 FIDO/WebAuthn 标准之上,利用公钥加密技术,天然抵御钓鱼和凭证填充攻击,在简化用户登录体验的同时,极大地提升了安全态势。对企业而言,这意味着实实在在的商业利益:降低了因密码重置和短信一次性密码(SMS OTP)产生的运营成本,减轻了账户被盗欺诈带来的财务风险,并通过更高的转化率增加了收入。
然而,WebAuthn 最强大的安全优势之一——其严格的、与源绑定的特性——也给拥有多样化数字足迹的全球品牌和公司带来了重大的现实挑战。根据设计,为特定 Web 域创建的 Passkey 会通过加密方式锁定到该域,这是防止钓鱼攻击的一项基本原则。虽然这是一个强大的安全功能,但当一个品牌在多个域上运营时,它会导致用户体验碎片化和混乱。
一个突出的例子是 Twitter 重塑品牌为 X。在 twitter.com 上创建了 Passkey 的用户会发现它在 x.com 上无法使用,这迫使该公司要么采用繁琐的重定向,要么要求用户重新注册,从而产生了直接阻碍 Passkey 普及的摩擦。这并非个例。像亚马逊这样的大型企业在众多国家代码顶级域名(ccTLD)上运营,如 amazon.com、amazon.de 和 amazon.co.uk,而它们都共享一个通用的用户账户系统。在 Passkey 出现之前,密码管理器能够熟练地处理这种复杂性,但 WebAuthn 的默认行为会要求每个域都拥有一个独立的 Passkey,这不仅让用户感到沮丧,也削弱了无缝登录的承诺。
为了解决这个严重影响普及的障碍,W3C 在 WebAuthn 标准中引入了一项新功能:关联源请求 (Related Origin Requests, ROR)。这个强大的机制提供了一种标准化、安全的方式,让一组受信任的域能够共享同一个 Passkey,从而在品牌的整个数字生态系统中创造统一、无缝的身份验证体验。本文将深入探讨 ROR 的技术基础,提供一个实用的实现指南,并分析其对现代身份验证架构的战略影响。
ROR 的引入标志着 WebAuthn 标准的重大成熟。最初的规范优先确立了核心的加密和安全原则,其中凭证与依赖方 ID (rpID) 的严格绑定是其反钓鱼设计的基石。随着像亚马逊和谷歌这样的公司进行大规模企业部署成为现实,这种僵化所带来的实际摩擦变得显而易见。这种摩擦直接阻碍了实现高用户采用率,而这正是任何 Passkey 项目最终的成功标准。ROR 的开发正是对这些企业反馈的直接回应,展示了标准的务实演进。它承认,一个安全协议要想取得广泛成功,其可用性必须能够扩展,以适应部署它的组织的复杂商业现实和品牌战略。
这份全面的指南将回答实现 WebAuthn 关联源请求的五个关键问题:
.well-known URI 机制。更多技术细节,请参阅官方 WebAuthn 关联源请求说明文档。
为了充分理解关联源请求解决方案的精妙之处,我们必须首先了解其存在背后的基础技术概念:Web 的同源策略和 WebAuthn 的依赖方 ID (rpID) 范围规则。这些机制是 Web 安全的基础,但也正是它们制造了 ROR 旨在解决的摩擦。
Web “源” (Origin) 是一个关键的安全概念,由提供内容的协议(如 https)、域(如 app.example.com)和端口(如 443)的唯一组合定义。同源策略是浏览器强制执行的一种安全机制,它限制了从一个源加载的脚本如何与另一个源的资源进行交互。这是 Web 安全的重要组成部分,能有效隔离潜在的恶意文档,并防止欺诈网站读取用户在另一个标签页中已登录的 Web 邮箱的敏感数据等。
在 WebAuthn 生态系统中,“依赖方” (Relying Party, RP) 是指用户试图进行身份验证的网站或应用程序。每个 Passkey 在创建时都会通过加密方式绑定到一个依赖方 ID (rpID)。rpID 是一个域名,它定义了该凭证的范围和边界。
默认情况下,rpID 是创建 Passkey 的源的有效域。WebAuthn 的范围规则允许一个源设置一个等于其自身域或其可注册域后缀的 rpID。例如,在 https://www.accounts.example.co.uk 上运行的脚本可以创建 Passkey,其 rpID 可以是:
www.accounts.example.co.uk(完整域)accounts.example.co.ukexample.co.uk这种灵活性允许在一个子域上创建的 Passkey 可以在同一父域的其他子域中使用,这是一种常见且必要的模式。然而,规则严格禁止设置一个非后缀的 rpID。在 www.accounts.example.co.uk 上的同一脚本_不能_创建 Passkey,其 rpID 设置为 example.com,因为 .com 是一个不同的顶级域。
这种严格的绑定有一个重要目的:按域范围分离凭证。为 mybank.com 创建的 Passkey 不能在 phishing-site.com 上使用,因为恶意网站无法声明 mybank.com 的合法 rpID。浏览器甚至不会将该 Passkey 作为选项呈现给用户。
然而,rpID 本身并非主要的反钓鱼控制手段。WebAuthn 的反钓鱼保护实际上来自 clientDataJSON 对象中的源验证。在每次 WebAuthn 流程中,浏览器都会创建一个包含关键上下文的 JSON 对象,其中包括发起请求的_确切源_。然后,整个对象会由认证器的私钥进行加密签名。服务器(依赖方)必须验证这个签名,并且至关重要的一点是,验证已签名的 clientDataJSON 中的 origin 字段是否与预期的、受信任的值匹配。这种源验证才是防止钓鱼攻击的关键。
通过关联源请求,rpID 的范围被放宽了——在浏览器验证了 .well-known/webauthn 文件后,允许 bar.com 合法地声明 foo.com 的 rpID——但源验证的要求保持不变。clientDataJSON 仍将如实报告源为 bar.com。位于 foo.com 的服务器接收到这个已签名的数据,进行验证,并看到请求来自 bar.com。然后,服务器必须检查 bar.com 是否是预期的关联源,然后才能接受身份验证。这展示了一种多层次的方法,既允许更大的灵活性,又不牺牲源验证的核心原则。
关联源请求机制引入了一种优雅且标准化的方式,让域可以公开声明一种信任关系,以共享 Passkey。它利用了一种成熟的 Web 模式——/.well-known/ URI,来创建一个可验证的、机器可读的“允许列表”,供浏览器查阅。
其核心概念很简单:一个作为一组关联网站的主要、规范性 rpID 的域,可以在一个标准化的、“众所周知”的 URL 上托管一个特殊的 JSON 文件:https://{rpID}/.well-known/webauthn。这个文件充当一个公开的清单,明确列出所有被官方授权在该主要 rpID 下创建和使用 Passkey 的其他源。
每当浏览器遇到当前源与请求的 rpID 不匹配时,就会触发浏览器的验证流程:
https://example.co.uk)上的用户发起一个 Passkey 操作(创建或认证),其中客户端代码指定了一个不同的域作为 rpID,例如 example.com。https://example.com/.well-known/webauthn。这个请求不带用户凭证(如 cookie)和 referrer 头,以保护用户隐私并防止跟踪。https://example.co.uk) 是否存在于 JSON 对象内的 origins 数组中。example.com 作为有效的 rpID。如果未找到源,或者文件丢失或格式错误,操作将像以前一样失败。选择使用 /.well-known/ URI 是经过深思熟虑的,它使 ROR 与既定的 Web 标准(用于服务发现和域控制验证)保持一致。这个由 RFC 8615 定义的 URI 路径已经被许多关键协议使用,包括用于 Let's Encrypt SSL 证书颁发的 acme-challenge 和用于将网站链接到 Android 应用程序的 assetlinks.json。通过采用这种惯例,W3C 利用了一种固有地暗示域所有权的模式。要在特定、标准化的路径上放置文件,必须对该域的 Web 服务器拥有管理控制权。这提供了一种简单而有效的控制证明,使信任声明变得可验证。当 example.com 的所有者提供一个将 example.co.uk 列为关联源的文件时,这是一个可验证的声明。这种 Web 原生的方法比在标准化过程中被考虑和拒绝的其他方案(如使用加密密钥签署授权的 RP Keys 或非基于域的随机标识符 RP UUIDs)要简单和稳健得多。ROR 将信任关系建立在 Web 现有且广为人知的域控制模型之上。
实现关联源请求需要在服务器端进行协调更改以授权源,并在客户端进行协调以调用共享的 rpID。本节提供了在您的域之间实现统一 Passkey 体验所需的实用代码和配置细节。
托管主要 rpID 的服务器负责发布关联源的允许列表。
授权文件必须放置在主要 rpID 域根目录下的确切路径 /.well-known/webauthn。至关重要的是,该文件必须在以下条件下提供:
Content-Type 必须设置为 application/json。.json 扩展名。正确的路径是 /webauthn,而不是 /webauthn.json。该文件必须包含一个单一的 JSON 对象,其中有一个键 origins,其值是一个字符串数组。数组中的每个字符串都是被授权的完整源(协议、域和可选端口)。
{ "origins": ["https://example.co.uk", "https://example.de", "https://example.fr"] }
示例: 对于 example.com 的 rpID,文件必须在 https://example.com/.well-known/webauthn(注意:没有 .json 扩展名)上提供。
一旦服务器配置了 .well-known/webauthn 文件,所有关联域都必须在其 WebAuthn API 调用中一致地使用同一个共享的 rpID。这种协调对于 ROR 的正常工作至关重要。
关键协调要求:
example.com、example.co.uk、example.de)必须将同一个共享的 rpID 传递给浏览器的 navigator.credentials API。即使只有一个站点配置错误——例如,它默认使用自己的源作为 rpID,而不是共享的值——也会破坏该域上用户的统一 Passkey 体验。
重要提示: 服务器必须为每个请求验证 clientDataJSON 中的 origin 字段,确保它与已授权的关联源之一匹配。这种源验证是主要的反钓鱼保护机制。
关联源请求 (ROR) 和联合身份协议 (OIDC/SAML) 解决的是不同的问题。 ROR 并不是单点登录的替代品,而是对其的补充,解决了特定且狭窄的用例。
ROR 适用于分布在多个相关域上、共享同一个用户数据库的单一逻辑应用程序:
amazon.com, amazon.de, amazon.co.uk)ROR 提供了什么: 同一个 Passkey 可以在所有关联域中使用,用户无需为每个地区站点创建单独的 Passkey。
对于跨不同应用程序的真正单点登录,请使用联合身份协议:
OIDC/SAML 提供了什么: 集中式身份验证,用户在身份提供商 (IdP) 登录一次,即可通过安全令牌访问多个服务提供商 (SP)。
重要提示: Passkey 可以在这两种方法中都使用。您可以在集中的 IdP 上实现 Passkey 以进行联合 SSO,也可以为多域单一应用程序使用 ROR。选择应基于您的架构,而不是您的身份验证方法。
虽然 ROR 是一个强大的技术解决方案,但其实施应是一个深思熟虑的战略决策。架构师和产品经理必须权衡其优势与替代方案,并了解其局限性,以构建一个稳健且面向未来的身份验证系统。
ROR 的一个关键限制是“标签限制”。此处的“标签”指的是有效顶级域名加一级(eTLD+1),也就是域名的可注册部分。例如:
shopping.com、shopping.co.uk 和 shopping.ca 都共享同一个标签 "shopping"myshoppingrewards.com 引入了一个新的、不同的标签:"myshoppingrewards"travel.shopping.com 仍然属于 "shopping" 标签WebAuthn Level 3 规范要求浏览器实现至少支持 origins 列表中的五个唯一标签。 截至 2025 年,没有已知浏览器支持超过这个最低的五个标签。因此,企业在设计 ROR 部署时应牢记这个硬性限制——将五视为有效的最大值。
这个限制是一种刻意的反滥用机制,旨在防止误用。它阻止了像共享托管提供商(例如 wordpress.com)这样的实体创建一个可以在成千上万个不相关的客户子域上工作的通用 Passkey,这会破坏安全模型。
对于大多数组织,即使是大型跨国品牌,这个五标签限制也是足够的。例如,亚马逊的各种国家代码顶级域名(amazon.com, amazon.de, amazon.co.uk 等)都共享“amazon”这个标签,这为他们的投资组合中的其他品牌(如“audible”或“zappos”)留下了四个额外的标签空位。
实现 ROR 的复杂性在很大程度上取决于是在新系统中引入,还是在现有系统上进行改造。
.com 域)。然后,这个 rpID 应该在所有相关网站和应用程序的配置中从第一天起就一致使用。了解知名公司如何实现关联源请求,可以为您的部署策略提供宝贵的见解。以下是基于实际实现(截至 2025 年 10 月)的例子:
微软在其身份验证基础设施中使用了 ROR。login.microsoftonline.com 的实际配置包括:
// https://login.microsoftonline.com/.well-known/webauthn { "origins": ["https://login.microsoftonline.com", "https://login.live.com"] }
这种保守的方法使得微软的企业和消费者登录门户之间可以共享 Passkey,同时保持了集中的安全边界。
Shopify 实施 ROR 以统一特定域的身份验证:
// https://shopify.com/.well-known/webauthn { "origins": ["https://shopify.com", "https://shop.app"] }
此配置允许 Shopify 将其主平台与他们的 Shop 应用连接起来,展示了一种专注的关联源方法。
亚马逊的文件相当大:
// https://amazon.com/.well-known/webauthn { "origins": [ "https://www.amazon.com", "https://www.amazon.com.br", "https://www.amazon.com.mx", "https://www.amazon.ca", "https://www.amazon.co.uk", "https://www.amazon.de", "https://www.amazon.it", "https://www.amazon.es", "https://www.amazon.nl", "https://www.amazon.se", "https://www.amazon.sa", "https://www.amazon.pl", "https://www.amazon.com.tr", "https://www.amazon.fr", "https://www.amazon.com.au", "https://www.amazon.sg", "https://www.amazon.ae", "https://www.amazon.eg", "https://www.amazon.co.za", "https://www.amazon.in", "https://brandregistry.amazon.com", "https://sellercentral.amazon.com", "https://sellercentral.amazon.com.br", "https://sellercentral.amazon.com.mx", "https://sellercentral.amazon.ca", "https://sellercentral.amazon.co.uk", "https://sellercentral.amazon.de", "https://sellercentral.amazon.it", "https://sellercentral.amazon.es", "https://sellercentral.amazon.nl", "https://sellercentral.amazon.se", "https://sellercentral.amazon.sa", "https://sellercentral.amazon.pl", "https://sellercentral.amazon.com.tr", "https://sellercentral.amazon.fr", "https://sellercentral.amazon.com.au", "https://sellercentral.amazon.sg", "https://sellercentral.amazon.ae", "https://sellercentral.amazon.eg", "https://sellercentral.amazon.co.za", "https://sellercentral.amazon.in", "https://na.account.amazon.com", "https://vendorcentral.amazon.com", "https://vendorcentral.amazon.com.br", "https://vendorcentral.amazon.com.mx", "https://vendorcentral.amazon.ca", "https://vendorcentral.amazon.co.uk", "https://vendorcentral.amazon.de", "https://vendorcentral.amazon.it", "https://vendorcentral.amazon.es", "https://vendorcentral.amazon.nl", "https://vendorcentral.amazon.se", "https://vendorcentral.amazon.pl", "https://vendorcentral.amazon.com.tr", "https://vendorcentral.amazon.fr", "https://vendorcentral.amazon.com.au", "https://vendorcentral.amazon.co.za" ] }
这种模式可以让一个品牌在区域域之间提供统一的 Passkey 身份验证,同时使用主要的 .com 域作为 rpID。
这些真实世界的例子揭示了几个关键模式:
作为一项现代 Web 标准,ROR 在设计时将安全性作为首要考虑,并正在各大主流浏览器中得到积极采纳。
关联源请求不会损害 WebAuthn 的核心反钓鱼保证。该机制经过精心设计,以保持强大的安全态势:
.well-known/webauthn 文件的请求是通过 HTTPS 进行的。此外,规范要求此获取操作不带凭证(如 cookie)和 Referer 头。这可以防止该请求被用于泄露用户信息或跨站跟踪。.well-known/webauthn 文件本身成为一项关键的安全资产。如果攻击者获得托管主要 rpID 的 Web 服务器的控制权,他们可能会修改此文件,将自己的恶意域添加到允许列表中。因此,保护提供此文件的基础设施至关重要。关联源请求是 WebAuthn Level 3 规范的一项功能。浏览器支持于 2024 年底开始推出:
| 操作系统 | 浏览器 / 平台 | 版本支持 | 状态 |
|---|---|---|---|
| Android | Chrome, Edge | 128+ | ✅ 支持 |
| Chrome OS | Chrome, Edge | 128+ | ✅ 支持 |
| iOS / iPadOS | 所有浏览器 (Safari) | iOS 18+ | ✅ 支持 |
| macOS | Chrome, Edge | 128+ | ✅ 支持 |
| macOS | Safari | Safari 18 (macOS 15+) | ✅ 支持 |
| Ubuntu | Chrome, Edge | 128+ | ✅ 支持 |
| Windows | Chrome, Edge | 128+ | ✅ 支持 |
| 所有平台 | Firefox | 不支持 | ⚠️ 使用备用方案 |
关键信息:
对于需要支持旧版浏览器或 Firefox 的应用程序,请实施备用策略:
PublicKeyCredential.getClientCapabilities() 检查是否支持 ROR。数据基于截至 2025 年 10 月的当前支持矩阵。
实现关联源请求需要多个技术团队之间的仔细协调和对 WebAuthn 协议的深入专业知识。Corbado 的Passkey 普及平台通过为多域 Passkey 部署提供企业级解决方案,消除了这种复杂性。
Corbado 通过以下方式处理关联源请求的技术复杂性:
.well-known/webauthn 文件,并带有正确的安全头和 JSON 格式。除了技术实现,Corbado 还提供企业所需的安全框架:
对于已有 Passkey 部署的组织,Corbado 提供:
准备好为您的组织实施关联源请求了吗?Corbado 的专家团队可以帮助您设计和部署一个统一的 Passkey 体验,覆盖您的整个数字生态系统。联系我们的解决方案团队,讨论您的具体需求和时间表。
Passkey 的前景在于它能够创造一个对用户来说既更安全又极其简单的未来。然而,要让这个未来在全球范围内成为现实,标准必须适应现代数字品牌的架构复杂性。严格绑定于域的 Passkey 所造成的摩擦,一直是拥有多方面在线业务的组织普及 Passkey 的一个重大障碍。
WebAuthn 关联源请求为这个问题提供了标准化的、安全的、优雅的解决方案。通过允许单个 Passkey 在一组受信任的关联域中无缝工作,ROR 消除了用户的一个主要困惑和挫败点。
本指南解决了实现 WebAuthn 关联源请求的五个关键问题:
.well-known/webauthn 文件来创建一个可验证的关联域允许列表,使浏览器能够通过安全的 HTTPS 获取过程验证跨域 Passkey 的使用。.well-known/webauthn 清单文件,以及客户端协调以在所有关联源中一致地使用共享的 rpID。对于技术团队和产品负责人来说,要点如下:
.well-known/webauthn 文件,并且所有客户端应用程序都必须配置为使用该同一个共享的 rpID。像关联源请求这样的功能对于无密码运动的持续发展至关重要。它们表明了标准机构致力于解决现实世界的实施挑战,确保 Passkey 的好处——无与伦比的安全性和轻松的用户体验——即使是最大、最复杂的组织也能够获得。随着这一功能获得普遍的浏览器支持,它将在打破通往一个真正全球化、无密码互联网的最后障碍方面发挥关键作用。
Related Articles
Table of Contents