WebAuthn 与 Passkey 实战:用浏览器原生无密码登录(公钥认证与替代短信验证码的完整流程)

#WebAuthn与Passkey实战:用浏览器原生无密码登录(公钥认证与替代短信验证码的完整流程)上个月十九号晚上快十一点,我盯着后台那张短信账单发呆。光验证码一项,三万七。更憋屈的是那个月被接码平台撸了两轮,羊毛党拿虚拟号段…

WebAuthn 与 Passkey 实战:用浏览器原生无密码登录(公钥认证与替代短信验证码的完整流程)

上个月十九号晚上快十一点,我盯着后台那张短信账单发呆。光验证码一项,三万七。更憋屈的是那个月被接码平台撸了两轮,羊毛党拿虚拟号段批量注册,验证码一条接一条发出去,跟往黑洞里扔钱没区别。第二天周会我把账单拍在桌上:这条路必须砍掉,谁来劝都没用。

有人建议换成动态口令。我没采纳。用户还是得装个应用、还是得抄那六位数,体验没好到哪去,钓鱼站照样能把码骗走。绕了一大圈,最后落在浏览器原生那条路上:WebAuthn 加 Passkey。说白了就是把"密码"这东西从我们系统里彻底删掉,改用一对密钥来证明"我是我"。

真正动手之后我发现,这事难点根本不在加密原理,而在一堆参数细节。我踩的第一个坑说出来挺丢人:本地开发一切正常,指纹一按就过;代码推到预发,控制台直接飘红——NotAllowedError: The relying party ID is not a registrable domain suffix of, nor equal to the current origin.我抱着"是不是证书链不对"的念头折腾了半个多小时,最后才发现配置里的rp.id还写着localhost。这个错误我后来又见过无数次,几乎每次都是同一个病因:域名没对齐。所以下面讲注册参数时,我会把这块单独拎出来。

密码和短信,究竟烂在哪

先说点大家都有体感的东西。我自己的邮箱密码管理器里躺着四百多条记录,其中一大半我压根不知道当初设的什么。换个新手机,第一件事不是装微信,是把密码管理器的同步打开——不然一堆账号当场变砖。用户不会为了你一个站单独记一个强密码,这是人性,别跟人性较劲。

更麻烦的是钓鱼。行业里常引用一组数字,说九成以上的攻击是从钓鱼邮件或者仿冒站点开始的,具体统计口径我没逐个核实,但方向不会错。钓鱼最恶心的地方在于:你的密码再复杂、哈希加盐加得再花哨,只要用户在假页面上老老实实敲了一遍,你这边做的所有防护就瞬间作废。短信验证码也一样,伪基站、接码平台、验证码转发木马,花样比防御手段多。

Passkey 的思路是把这个博弈直接掀桌子。登录时网络上不再出现任何"可被偷走就能冒充你"的东西。用户设备上藏着一把私钥,服务器上存的是对应的公钥。登录的时候,设备拿私钥对一个一次性挑战值签名,服务器拿公钥验签。签对了就放行。私钥从头到尾不出设备——你手机丢了都导不出来,更别说隔着网络偷。

还有个我觉得被严重低估的好处:抗钓鱼是协议层自带的。你注册时凭据绑定了域名,仿冒站哪怕把 UI 做得一模一样,域名对不上,设备压根不会给你签这个名。这不是靠用户"擦亮眼睛",是靠密码学兜底。

这里要分清楚两个词,很多人混着用,我一开始也搞不清。WebAuthn 是浏览器标准,Passkey 是建立在其之上的一套产品化约定。普通 WebAuthn 凭据往往只用来给已有账号做第二步验证,服务端已经知道你是谁了;而 Passkey 多了一层"可发现性",凭据能自己告诉服务端"我是谁",所以才能做到不输用户名直接登录。差别就出在 residentKey 这个参数上,后面会讲到。另外 Passkey 支持跨设备同步,你在手机上创建的凭据,同一把钥匙串下的平板、电脑都能用。我自己在 iPhone 上注册完,MacBook 上直接就登进去了,那一刻确实有点小激动——不过也意味着你的钥匙串账号本身成了新的单点,这个风险得认。

先别急着写代码,环境这关就卡人一半

WebAuthn 只能在安全上下文里跑,这是硬要求。HTTPS 或者 localhost 例外,其他裸 HTTP 的部署环境直接不可用,连 API 都不会挂载。我那次预发挂掉其实有两层原因,域名写错是一层,预发当时还挂在 http://上是另一层——两个坑叠一块,报错信息还一模一样,排查起来特别想骂人。

还有个隐藏更深的限制:只能在顶层浏览上下文调用。把登录逻辑塞进 iframe 里,比如嵌在第三方站点里的登录框,调用会直接失败。飞书、企业微信那种内嵌 WebView 也经常踩这里。真遇到这种情况,得走 Permissions-Policy把publickey-credentials-get和publickey-credentials-create放出来,但说实话我更建议跳转顶层页面登录,省事。

写业务代码之前,先探一下设备能力,别上来就弹认证框。我一般这么写:

js
复制
// 能力探测:三个特性缺一不可,别在不支持的机器上直接弹登录框async function checkPasskeySupport() { // 没有 PublicKeyCredential,说明浏览器压根没实现 WebAuthn if (!window.PublicKeyCredential) return false; // 平台认证器(Windows Hello / Touch ID / 指纹)能不能做用户验证 const hasPlatform = await PublicKeyCredential .isUserVerifyingPlatformAuthenticatorAvailable(); // 条件中介:决定能不能做"免输用户名自动填充"那种丝滑登录 const hasConditional = await PublicKeyCredential .isConditionalMediationAvailable(); return hasPlatform && hasConditional;}

这里有个细节容易被忽略:isUserVerifyingPlatformAuthenticatorAvailable() 返回真,只代表"这台设备有能验证用户身份的平台认证器",不代表它一定给你弹出生物识别。有些 Windows 机器没设 PIN、没配 Windows Hello,这个方法照样可能返回真,到真正调用时却一声不响地失败。我的做法是探测通过之后仍然保留短信验证码作为兜底入口——至少在迁移期必须这样,别一上来就把老路径删干净。

MDN 上 PublicKeyCredential 的文档写得很清楚,浏览器支持面现在其实已经不错了,但平台认证器探测和条件中介这两项仍要按兼容表核对,别默认所有机器都能弹本机指纹。

注册:一次性 challenge 是整条链路的命门

注册这套流程,服务端和浏览器各干一半。服务端负责生成随机挑战值并存起来,浏览器负责调认证器生成密钥对,然后把结果送回服务端验。前端这里最重要的认知是:你拿到的 options 里,challenge 必须原样传回去,一个字节都不能动。

我犯过的蠢是刷新页面之后继续用旧的 challenge 提交,结果就是那种"偶尔能用、偶尔报错"的灵异现象。原因很简单:challenge 是一次性的,服务端验完就删了。你拿旧的去验,服务端找不到对应记录,只能报一个含糊的错。所以 challenge 的生命周期我给自己定了死规矩:每次注册或登录都重新生成,两到五分钟过期,按会话存服务端,验证成功立刻删。

下面是注册参数,我把容易出事的字段都标了注释:

js
复制
// 注册:把服务端返回的 JSON 转回 ArrayBuffer 再交给浏览器// 服务端负责生成 challenge 并暂存,前端只负责原样传回const creationOptions = { challenge: base64urlToBuffer(json.challenge), // 一次性随机串,专门防重放 rp: { name: '前端哥技术博客', // 展示用名称,随便写 id: 'example.com' // 必须是当前域或其可注册父域,填错直接 NotAllowedError }, user: { id: crypto.getRandomValues(new Uint8Array(16)), // 随机二进制 ID,别拿邮箱当 id,它会落进认证器 name: 'penn@example.com', // 账号,仅展示 displayName: '笔澜' // 昵称,仅展示 }, pubKeyCredParams: [ { type: 'public-key', alg: -7 }, // ES256,主流首选 { type: 'public-key', alg: -257 } // RS256,兼容个别老设备 ], authenticatorSelection: { authenticatorAttachment: 'platform', // 只要本机生物识别,暂不接外部 U 盾 residentKey: 'required', // 凭据落在认证器上,才能免用户名登录 userVerification: 'preferred' // 写 required 会把没设 PIN 的设备直接拒掉 }, timeout: 60000, attestation: 'none' // 不收集证明证书,省掉隐私争议和传输体积};const credential = await navigator.credentials.create({ publicKey: creationOptions });

rp.id那行我要多啰嗦两句,因为它是我职业生涯里交学费最多的参数。规则是这样的:当前页面在app.example.com,那么rp.id写app.example.com可以,写父域example.com也可以(这样多个子域能共享凭据),但写other.example.com或者example.org 就统统不行。跨域是彻底禁止的,没有"差不多就行"这回事。另外子域可以用父域的 id,反过来不行——别想着在 example.com 上注册一个 id 为 login.example.com的凭据。

residentKey: 'required' 是另一个关键点。这个值不设成 required,凭据就只存在服务端、靠 allowCredentials列表才能找到,登录时用户还是得先输用户名。想要那种"点一下登录、指纹一按就进"的效果,凭据必须可发现,也就是必须落在认证器本地。我后来把userVerification从required改成preferred,也是被现实教育的结果——设成 required 之后,一堆没配生物识别也没设 PIN 的机器直接登录失败,客服工单差点把我淹了。

顺带一提,登录框那个自动填充的 UI,我一开始手写了一堆显示隐藏逻辑,后来看了 CSS :has() 关系选择器实战:用"父级选子级"写出更聪明的组件样式(链式与 :not() 组合)那篇,改成用关系选择器根据输入框状态控制提示层的显隐,省掉不少 JS。前端这种小场景,能用样式解决就别往 state 里塞。

浏览器返回的东西,不能直接 JSON.stringify

navigator.credentials.create()成功后返回的是一个PublicKeyCredential对象,里面的关键字段全是ArrayBuffer。这里有个坑特别阴:你要是直接JSON.stringify(credential),那些ArrayBuffer会全变成空对象{},服务端收到一堆空的壳子,验签时一脸懵。我就这么干过,还以为是后端解析库有 bug。

正确做法是每个字段单独做 base64url 编码。注意是 base64url,不是普通 base64——+和/ 在 URL 和 JSON 传输里容易惹事,尾部 padding 也得去掉:

js
复制
// 浏览器返回的 credential 不能直接 JSON.stringify,ArrayBuffer 会变成 {}// 必须逐个字段做 base64url 编码再送回服务端function bufferToBase64url(buffer) { const bytes = new Uint8Array(buffer); let binary = ''; for (const b of bytes) binary += String.fromCharCode(b); return btoa(binary) .replace(/\+/g, '-') // 标准 base64 的 + 换成 - .replace(/\//g, '_') // 标准 base64 的 / 换成 _ .replace(/=+$/, ''); // 去掉尾部 padding}const payload = { id: credential.id, rawId: bufferToBase64url(credential.rawId), type: credential.type, response: { clientDataJSON: bufferToBase64url(credential.response.clientDataJSON), attestationObject: bufferToBase64url(credential.response.attestationObject) }};await fetch('/api/passkey/register/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload)});

服务端拿到之后,从clientDataJSON 里解出 JSON,核对三件事:type必须是webauthn.create、challenge必须和刚才下发的一次性值完全一致、origin必须精确等于你信任的源。注意是精确匹配白名单,不能用includes或者字符串包含判断——我见过有人图省事写origin.includes('example.com'),那evil-example.com就堂而皇之地通过了。

这套校验我强烈建议直接交给成熟的服务端库去做,比如 Node 生态里的 SimpleWebAuthn,Java 这边有 Yubico 的 webauthn-server。我一开始头铁,想自己把验签流程撸一遍,结果光是 COSE 公钥转 PEM 就卡了半天,不同的认证器返回的算法编号还不一样。后来老老实实换库,一个下午就跑通了。密码学这东西,实现细节里全是坑,交给专门维护的库才是正解——这不是偷懒,是对用户负责。

challenge 存在哪儿也有讲究。我用 Redis 的 hash 结构,注册的 options 按用户编号存一份,认证的 options 按会话编号存一份,验证完当场删掉。存的时候序列化成 JSON,取的时候反序列化回来。这里要设个过期时间,我一般给五分钟,防止用户开了页面半天不操作、一堆僵尸 options 堆在内存里。另外签名计数器要跟凭据一起落库,公钥、凭证编号、传输方式、认证器标识这些也全存下来——只存一个凭证编号,后面出问题想排查都没有线索。

attestationObject里解出来有authData、fmt、attStmt,公钥就藏在authData里。因为我们前面设了attestation: 'none',服务端不需要去验证证书链,直接从authData 抠出 COSE 格式的公钥存库就行。COSE 公钥转成各语言能用的格式是另一个坑,好在各家服务端库都封装好了,别自己手撸 CBOR 解码——我劝你一句,这种底层密码学的东西,交给成熟的库比自己写靠谱得多。

登录:终于到无用户名这一步

注册做完,登录就顺理成章了。这里最爽的地方是"去用户化":登录前服务端根本不知道你是谁,用户也不用输账号。浏览器问认证器要凭据,认证器列出这台设备上所有属于当前站点的 Passkey,用户挑一个、按一下指纹,完事。

条件中介要做好两件事。一是输入框必须带autocomplete属性,二是调用get()时传mediation: 'conditional'。少了任何一个,浏览器都不会在输入框的候选列表里列出 Passkey:

html
复制
<!-- 条件中介要求输入框声明 autocomplete,浏览器才会在候选里列出 Passkey --><input id="email" name="email" type="text" autocomplete="username webauthn" placeholder="邮箱或通行密钥">

然后是 JS 侧:

js
复制
// 登录:allowCredentials 留空 + residentKey required,才能不输用户名const requestOptions = { challenge: base64urlToBuffer(assertionJson.challenge), // 全新的一次性 challenge rpId: 'example.com', // 必须和注册时的 rp.id 一致 userVerification: 'preferred', timeout: 60000 // allowCredentials 不传,让认证器自己列出这台设备上可用的凭据};// 条件中介:输入框声明了 autocomplete 后,自动弹出 Passkey 候选const assertion = await navigator.credentials.get({ publicKey: requestOptions, mediation: 'conditional'});// 注意:这里只是演示签名数据的拼法,真正的验签必须放在服务端做const assertionPayload = { id: assertion.id, rawId: bufferToBase64url(assertion.rawId), type: assertion.type, response: { authenticatorData: bufferToBase64url(assertion.response.authenticatorData), clientDataJSON: bufferToBase64url(assertion.response.clientDataJSON), signature: bufferToBase64url(assertion.response.signature), userHandle: assertion.response.userHandle ? bufferToBase64url(assertion.response.userHandle) : null }};

登录返回的是AuthenticatorAssertionResponse,跟注册的AuthenticatorAttestationResponse不是一个东西。重点字段是signature——这才是登录的凭证本体;userHandle是可选的,用来把这次断言关联到服务端的具体用户,做免用户名登录时全靠它认人。

有个真实项目里极易踩的坑:浏览器的凭据已经生成了,服务端却还没写完数据库就返回了成功。用户下次登录,设备上有凭据、服务端不认识,报一个泛泛的NotAllowedError。排查时你会以为是凭据丢了,其实是自己写入失败没处理。我的原则是:只有凭据真正落库之后,验证接口才返回成功。

验签和签名计数器,别偷懒

服务端验签的核心公式只有一行:被签名的数据等于authenticatorData拼接上clientDataJSON 的 SHA-256 哈希,两段直接首尾相接,中间不加任何分隔符。用注册时存下来的公钥验这个签名,验过就说明对方确实握着私钥。

js
复制
// 服务端验签示意(Node 版,生产环境建议用 SimpleWebAuthn 这类成熟库)const { createHash, verify } = require('node:crypto');// 签名数据 = authenticatorData || SHA-256(clientDataJSON),直接用 Buffer.concat 拼接const clientDataHash = createHash('sha256') .update(Buffer.from(clientDataJSON, 'base64url')) .digest();const signedData = Buffer.concat([ Buffer.from(authenticatorData, 'base64url'), clientDataHash]);const ok = verify( 'sha256', // ES256 用 SHA-256;RS256 也是它 signedData, publicKeyObject, // 注册时落库的公钥,需转成 KeyObject Buffer.from(signature, 'base64url'));// signCount 每次认证会递增,回退就说明凭据可能被克隆了if (!ok || signCount < storedSignCount) { throw new Error('签名无效或计数器回退,按凭据克隆处理');}

signCount这个字段我希望你认真对待。它是认证器维护的一个递增计数,每次认证加一。如果某次登录发现计数器比库里存的小,说明同一把私钥可能在两个地方被同时使用——大概率是凭据被克隆了。我的处理方式是先降级到短信验证码二次核验,同时给用户发告警,人工确认没问题再放行。直接拒绝登录反而会误伤用户,比如某些平台的认证器实现压根不递增计数器(永远返回零),这种就别拿计数器较真。

多凭据也得考虑。我现在给每个账号至少允许注册两个 Passkey,一个手机、一个硬件密钥。手机丢了不至于进不去账号。同时保留恢复码或者邮箱魔法链接作为找回路径——这条是血泪教训:凭据一旦全丢,又没有找回手段,用户是真的彻底进不来,谁也救不了。

测试矩阵这块也别省。我最后固定测三类组合:Windows Hello、手机上的 Passkey、USB 硬件密钥。它们对 residentKey 和用户验证的支持差别大得离谱,同一套参数在 A 上顺滑、在 B 上直接失败是常态。调试阶段强烈建议先开浏览器的 WebAuthn 模拟器,别一上来就在生产环境折腾生物识别弹窗——我干过一次,对着真机按了二十分钟指纹,最后发现是参数写错,人都麻了。

还有个 userHandle 的坑值得单独说:注册时务必生成一个稳定、唯一的二进制用户编号,别用邮箱、手机号这种可能变动的字段。我早期图省事拿数据库自增编号直接转字节,后来用户改邮箱没事,但只要涉及账号合并就乱套。这东西一旦写进认证器就改不了了,前期多花十分钟想清楚,能省后面十倍的返工。

至于硬件密钥,如果你要接 USB 安全密钥那条线,浏览器侧读写设备的部分可以参考 Web Serial API 实战:在浏览器里直接读写串口与硬件设备(requestPort 与数据流收发),不过 WebAuthn 场景里认证器交互是浏览器托管的上层协议,不需要你自己去操作串口,那篇更多是帮你理解底层设备通信是怎么回事。

短信验证码怎么退场

砍掉短信验证码这件事,我最后没做成"一刀切"。迁移期是这样的:老用户照旧能走短信,登录页多一个"用通行密钥"的按钮;新用户注册完默认引导创建 Passkey,创建成功就把短信验证降级为备用。跑了一个月,Passkey 的登录占比到了六成多,接码平台的攻击基本归零——因为攻击者拿不到那台设备上的私钥。

这里的取舍我很明确:不要为了"技术先进"把用户逼到死角。有些用户的设备就是不支持,有些企业环境锁得死死的,你得给他留一条路。安全强度的提高不能以甩掉一部分用户为代价,这是产品决策,不是纯技术问题。上线之后我还会盯一个指标:Passkey 注册的失败率。这个数字比登录成功率更能反映问题,因为它卡在生物识别弹窗那一步,用户放弃了你连日志都拿不到。掉了就把兜底路径的入口做得更明显一点,别藏着。

还有个容易被忽略的点:删除凭据必须做二次验证。盗号的第一步往往就是把你的 Passkey 删掉,让用户退回弱验证方式。这个接口你得按高危操作对待,短信、邮箱、已有凭据至少验一样。

另外别把 WebAuthn 跟别的多媒体能力搞混,它是纯粹的认证协议,跟锁屏、车机控制面板那套完全不是一回事——那块是 Media Session API 实战:让网页音频接管锁屏与车载控制面板(元数据与播放控制) 的地盘。前端这两年冒出来的新 API 太多,名字一个比一个唬人,真上手还是得一个个把文档啃过去。

服务端那层数据结构如果换个技术栈,比如 PHP,我一般用 PHP 8.4 Property Hooks 实战:用属性钩子告别样板 Getter/Setter(虚拟属性与接口约束) 的思路把 DTO 里那堆样板 getter 收掉;Java 这边就得靠 Lombok 或者 record 了。语言不同,折腾的姿势不同,踩的坑倒是惊人的一致。

最后说句实在话:Passkey 这套东西的原理并不难,难的是全链路的参数对齐和异常兜底。challenge 一次性、rp.id 精确匹配、origin 白名单、residentKey 要 required、userVerification 别写死 required、签名计数器要存——这几条记住,能省你至少两天排查时间。剩下的,就是老老实实把成熟库用起来,别自己造密码学的轮子。

标签:WebAuthn, Passkey, 无密码登录, 公钥认证, 前端安全描述:从一次短信验证码账单事故出发,完整拆解 WebAuthn 与 Passkey 的注册和登录流程,讲清 challenge 防重放、rp.id 域名绑定、residentKey 可发现凭据、签名计数器与验签细节,给出浏览器端和服务端的可运行代码,帮你用浏览器原生公钥认证替代短信验证码。

4ooane8yih4ooane8yih
评论

评论列表共有0条评论

发表评论发布评论后审核成功,即可显示在列表中...

文章2
粉丝0
获赞0
私信