科技行业

2026 年的 Passkeys 与 WebAuthn:面向 Web 开发者的实用实现指南

Passkeys and WebAuthn in 2026: A Practical Implementation Guide for Web Developers

Passkeys 承诺实现无密码登录而不存储密码秘密,但正确实现 WebAuthn 需要的不仅仅是调用浏览器 API。了解如何将注册、身份验证、服务器端验证、可发现凭证和账户恢复整合到安全的 Web 应用中。

2026 年 Passkeys 和 WebAuthn:Web 开发者的实用实施指南

几十年来,密码一直是 Web 应用程序的默认身份验证机制,但同时也是安全问题的一个持久来源。

用户会重复使用密码,攻击者会通过网络钓鱼窃取密码,服务器则需要保护密码哈希、管理密码重置,并防御凭证填充攻击。

Passkeys 提供了一种全新的方法。

Passkeys 不要求用户记住共享的秘密,而是使用公钥加密技术和由用户控制的认证器。浏览器通过 WebAuthn 提供标准接口,而服务器则验证使用正确凭证的加密证据。

该技术已不再是实验性的。WebAuthn 在现代浏览器中已广泛可用,其 JSON 便捷方法大大简化了集成过程。

但构建安全的 Passkey 登录仍然需要精心设计后端架构。

本指南解释了架构,演示了浏览器端的流程,并指出了开发人员不应忽视的服务器端检查。

1. Passkey 究竟是什么?

Passkey 是一种可发现的 FIDO 凭证,用于通过公钥加密技术对用户进行身份验证。

在注册过程中,认证器创建一个加密密钥对。

私钥由认证器或其凭证管理生态系统保护。网站接收相应的公钥,并将其与用户帐户关联。

在身份验证过程中,服务器生成一个新的挑战。认证器对与该挑战相关的数据进行签名,服务器使用存储的公钥验证签名。

不会向网站发送任何可重用的密码。

认证器可以是智能手机、使用 Windows Hello 的计算机、硬件安全密钥或支持同步 Passkey 的凭证管理器。

并非每个 Passkey 都能在设备之间同步。某些凭证仍然绑定到设备,而其他凭证可以安全地备份并通过凭证提供程序提供。

FIDO 规范旨在通过将凭证绑定到依赖方的域名来抵抗网络钓鱼。当使用生物识别数据时,设备会将其本地处理,而不是将其发送到网站。

2. WebAuthn 是 Passkey 背后的浏览器 API

WebAuthn 是 Web 平台 API,允许网站创建和使用公钥凭证。

两个浏览器方法构成了基础:

navigator.credentials.create()
navigator.credentials.get()

第一个方法创建凭证。第二个方法请求使用现有凭证进行身份验证。

这两个方法都与 publicKey 选项一起工作,并且需要安全的上下文,通常是 HTTPS。

重要的是,浏览器不会决定用户是否已通过身份验证。它返回的数据需要后端进行验证。

浏览器的成功提示并不意味着登录应该被接受。

服务器仍然负责验证挑战、原点、依赖方标识符和加密证据。

3. 了解完整的架构

典型的实现包含四个组件:

  • Web 应用程序前端,它调用 WebAuthn。
  • 应用程序后端,它生成挑战并验证响应。
  • 认证器或 Passkey 提供程序,它保护私钥。
  • 数据库,它存储凭证元数据和公钥。

注册流程如下:Web 应用程序请求注册选项;后端生成挑战和用户数据;浏览器和认证器创建一个凭证和密钥对;后端验证结果并存储公钥。

服务器绝不能仅仅因为数据是由浏览器返回的就信任注册数据。

恶意客户端可以提交任意 HTTP 请求,而根本不使用预期的前端。

这就是为什么验证应该在服务器端进行的原因。

4. 在服务器端生成注册选项

在调用 WebAuthn 之前,后端需要生成注册挑战和选项。

一个示例选项对象如下所示:

{
  "rp": {
    "name": "Example Application",
    "id": "example.com"
  },
  "user": {
    "id": "dXNlci0xMjM",
    "name": "alex@example.com",
    "displayName": "Alex"
  },
  "challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "required"
  },
  "attestation": "none",
  "timeout": 300000
}

这是一个示意性的 JSON 实例,而不是完整的生产级响应。

几个字段很重要。

rp.id 标识依赖方。例如,example.com 可以用于该域的适当子域,但需遵守 WebAuthn 的 RP ID 验证规则。

user.id 应该是一个稳定的、不透明的账户标识符,用 base64url 编码用于 JSON 传输。它不应该暴露不必要的个人信息。

challenge 必须在服务器上使用加密安全的随机源生成。

residentKey: "required" 请求一个可发现的凭证,这是 Passkey 体验所必需的。

userVerification: "required" 请求本地用户验证,例如设备 PIN 或生物识别认证。后端必须检查验证是否实际上发生了。

Google 的服务器端注册指南描述了这些字段,并建议使用维护的 WebAuthn 库来生成和验证注册数据。

5. 使用 JavaScript 创建 Passkey

现代浏览器提供了一个有用的方法:

PublicKeyCredential.parseCreationOptionsFromJSON()

它将包含 base64url 编码二进制字段的 JSON 表示转换为 WebAuthn 期望的结构。

这避免了为每个字段编写自定义 base64url-to-ArrayBuffer 转换逻辑。

以下是一个简化的浏览器端注册函数:

async function registerPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/register/options',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            }
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start registration');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseCreationOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.create({
        publicKey
    });

    if (!credential) {
        throw new Error('No credential was created');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/register/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Registration verification failed');
    }

    return await verifyResponse.json();
}

csrfToken 变量代表应用程序提供的反 CSRF 令牌。服务器必须对其进行验证。该示例还假设页面已经与安全身份验证的用户关联。

credential.toJSON() 提供了返回凭证的 JSON 友好表示,避免了另一层手动二进制序列化。

这些便捷功能在当前浏览器中可用,但支持旧浏览器版本的应用程序应提供兼容性处理。

上面的代码只是浏览器端的一部分。它不是一个完整的身份验证实现。

6. 注册期间服务器必须验证的内容

当浏览器返回新凭证时,后端必须在存储任何内容之前对其进行验证。

验证过程至少必须确定以下几点:

  1. 返回的挑战与为此注册尝试生成的挑战匹配。
  2. 挑战是新鲜的,并且尚未被使用。
  3. 报告的原点与明确信任的应用程序原点匹配。
  4. 认证器数据对应于预期的 RP ID。
  5. 满足必需的用户存在和用户验证条件。
  6. 凭证的公钥和标识符可以提取并验证。
  7. 注册与正确的已验证帐户关联。

根据应用程序的策略,额外的检查可能包括支持的算法、凭证唯一性和认证要求。

成功的注册通常存储以下内容:

字段 目的
credential_id 标识凭证
user_id 将其链接到帐户
public_key 验证未来的签名
sign_count 跟踪认证器计数器数据
transports 可选的认证器传输提示
created_at 注册时间戳
last_used_at 账户管理和审计
backup_eligible / backup_state 可选的备份相关元数据

确切的数据库表示取决于验证库和应用程序。

除非您有令人信服的原因和维护经验,否则不要从头开始实现 CBOR 解析、认证验证或加密签名验证。

W3C 规范定义了详细的注册和身份验证验证程序。

7. 对现有用户进行身份验证

身份验证遵循类似的结构,但不创建新的密钥对。

服务器生成一个新挑战,并将身份验证选项发送到浏览器。

对于可发现的 Passkey 登录,这些选项可能包含:

{
  "challenge": "NEW_SERVER_GENERATED_CHALLENGE",
  "rpId": "example.com",
  "userVerification": "required",
  "timeout": 300000
}

然后,浏览器可以请求凭证:

async function authenticateWithPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/login/options',
        {
            credentials: 'same-origin'
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start authentication');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseRequestOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.get({
        publicKey
    });

    if (!credential) {
        throw new Error('Authentication was cancelled');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/login/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Authentication failed');
    }

    return await verifyResponse.json();
}

该示例假设后端将发布的挑战与一个短期、匿名登录事务关联,应用适当的速度限制,只有在成功验证后才建立新的已验证会话。

服务器必须查找凭证 ID,使用存储的公钥验证签名的断言,确认挑战和原点,并强制执行其用户验证策略。

只有这样,它才应该建立用户的会话。

parseRequestOptionsFromJSON() 是现代 WebAuthn API 的一部分,去除了在常见浏览器端集成中手动解码二进制字段的需要。

8. 使用条件调解将 Passkeys 添加到现有登录表单

WebAuthn 最重要的功能之一是条件调解,有时被称为 Passkey 自动填充。

浏览器可以在用户与登录字段交互时,提供一个可用的 Passkey,同时提供其他保存的凭证,而不是立即显示一个单独的 Passkey 对话框。

HTML 输入可以使用:

<input
    type="text"
    name="username"
    autocomplete="username webauthn"
>

应用程序可以检查支持情况:

const supported =
    await PublicKeyCredential.isConditionalMediationAvailable();

if (supported) {
    // Request authentication with mediation: 'conditional'.
}

在调用 navigator.credentials.get() 时,应用程序使用:

{
    publicKey,
    mediation: 'conditional'
}

对于可发现凭证自动填充,服务器的选项不应将请求限制为特定的凭证 ID 列表。

条件调解在从密码逐步迁移时特别有用,因为用户不需要记住某个帐户是否有 Passkey。

浏览器可以在熟悉的登录体验中提供适当的选项。

9. 为什么挑战和原点检查至关重要

Passkeys 是防网络钓鱼的,但这并不意味着应用程序可以忽略其身份验证协议。

挑战可以防止重放攻击。

如果没有一个新鲜、不可预测的挑战,攻击者可能会尝试重用之前会话的身份验证数据。

原点和 RP ID 检查确保凭证在预期网站上下文中使用。

例如,为 example.com 创建的 Passkey 不能简单地被类似的网络钓鱼网站(如 examp1e.com)重用。

浏览器和认证器强制执行此域绑定的关键部分,而后端则独立验证由此产生的数据。

良好的实现使用短期挑战,每次消耗一个挑战,绝不接受任意原点,仅仅因为它们具有熟悉的主机名。

MDN 建议在可信环境中生成挑战,并在短时间内使其失效,一般不超过约十分钟。

10. 不要误解签名计数器

WebAuthn 认证器可以包含签名计数器。

历史上,计数器有助于检测潜在的克隆认证器。如果计数器意外地停止增加,依赖方可以将其视为风险信号。

但是,并非每个认证器都会维护一个有意义的计数器。

某些凭证总是报告零。同步凭证也会使计数器解释复杂化,因为多个设备可能使用同一凭证的副本。

W3C 规范明确地将意外的计数器行为视为一个可能的信号,而不是克隆的明确证据。

因此,开发人员不应盲目拒绝每个计数器为零或未更改的登录。

应根据认证器行为、WebAuthn 验证库的指导和应用程序的安全策略来使用计数器。

11. 账户恢复是 Passkey 安全的一部分

如果没有恢复策略,Passkey 实现就不完整。

当用户丢失设备时会发生什么?

如果他们删除了唯一的 Passkey,会发生什么?

如果他们更改凭证提供程序或无法访问同步凭证,会发生什么?

一个合理的设计允许用户注册多个 Passkey,并从他们的帐户设置中管理它们。

管理界面应该显示可识别的凭证名称、创建时间和可用时的最近使用信息。

用户应该能够撤销他们不再信任的凭证。

但恢复机制值得特别小心。

如果攻击者可以使用弱电子邮件恢复过程来绕过 Passkey 身份验证,那么整个帐户的安全性就仅限于该恢复路径。

对于高风险账户,请考虑更强大的恢复验证、恢复代码、额外的注册认证器以及关于敏感账户更改的通知。

Google 的 Passkey UX 指南建议建立恢复方法,并在适当的情况下支持多个 Passkey。

12. 常见的实现错误

几个错误反复破坏着原本有前景的 Passkey 集成。

将浏览器成功视为服务器身份验证。 解析过的 navigator.credentials.get() 承诺并不取代服务器端加密验证。

在 JavaScript 中生成挑战。 挑战应该来自可信的服务器,并与适当的身份验证事务绑定。

使用错误的 RP ID。 域名范围是一个安全功能,而不是装饰设置。生产、测试和本地开发环境需要仔细配置。

假设所有 Passkey 都会同步。 设备绑定的凭证仍然是生态系统的重要组成部分。

忘记凭证撤销。 用户需要一种方法来从他们的帐户中删除丢失或受损的认证器。

创建弱回退机制。 如果账户恢复可以轻易地被利用,一个防网络钓鱼的登录就会失去大部分价值。

忽略旧浏览器。 现代 JSON 便捷方法减少了复杂性,但具有旧浏览器要求的应用程序可能仍然需要兼容性代码。

跳过 CSRF 和会话保护。 注册和凭证管理操作是敏感的账户更改。它们需要与其他高影响账户操作相同的保护。

不必要地编写自定义加密验证。 使用维护的 WebAuthn 服务器库通常比直接实现规范更安全。

13. 每个网站是否应该立即更换密码?

不一定。

Passkeys 可以同时提高可用性和安全性,但迁移策略很重要。

对于一个新应用程序,如果产品有设计良好的恢复流程并支持其目标平台,那么无密码注册可以是一个合理的默认选项。

对于一个拥有数千用户的现有应用程序,增量采用通常更安全。

首先允许已验证的用户在帐户设置中注册 Passkey。

然后,在现有的身份验证系统中添加 Passkey 登录。

在支持的情况下引入条件调解。

衡量注册成功率、身份验证失败率、设备兼容性和恢复请求。

最后,一旦用户体验和恢复机制足够成熟,可以考虑将 Passkey 作为首选身份验证方法。

分阶段部署也可以更容易地识别与浏览器相关的問題,而不会将合法用户锁定在门外。

14. 生产就绪检查清单

在生产中启用 Passkeys 之前,请验证以下内容:

  • 所有 WebAuthn 操作都在适当的受保护上下文中运行。
  • RP ID 和受信任原点已明确配置。
  • 挑战是加密安全的随机数,短时效且一次性使用。
  • 注册需要适当的账户授权。
  • 服务器端验证遵循 WebAuthn 规范。
  • 公钥和凭证标识符以安全的方式存储。
  • 登录只有在成功验证后才建立会话。
  • 服务器强制执行用户验证要求。
  • 凭证删除和账户恢复受到保护。
  • 适当支持每个帐户有多个凭证的情况。
  • 监控身份验证失败和安全敏感的账户更改。
  • 测试移动、桌面、跨设备和硬件密钥场景。

这些检查比前端能否显示一个吸引人的生物识别登录提示更重要。

结论:Passkeys 是一种身份验证架构,而不仅仅是浏览器功能

WebAuthn 使公钥身份验证可用于普通 Web 应用程序。

现代浏览器 API 移除了以前使 Passkey 集成变得繁琐的大部分序列化工作。

但浏览器只是系统的一部分。

真正的实现工作在于挑战管理、服务器端验证、凭证存储、域名配置、账户恢复和安全的用户旅程。

对于使用 PHP、JavaScript、Python 或其他后端环境的开发人员来说,构建现代应用程序时,Passkey 作为传统密码的替代方案越来越值得考虑。

最好的起点不是一夜之间替换整个身份验证系统。

而是在实现一个完整且经过正确验证的注册和登录流程,然后围绕它建立一个安全的迁移策略。