Credential Management API 想解决的,是浏览器、网站与身份提供方三方各管一段登录态所造成的重复登录、令牌泄露与自动填充错乱。它把密码、联合身份与通行密钥收进一套标准化接口,但真正难的是安全语义与降级策略,而不是调用本身。

一、问题定位:登录态为什么总是"各管一段"

生产环境里,登录态从来不是一处,而是三处:浏览器密码管理器保存的账号密码、身份提供方(IdP)持有的会话 Cookie、业务服务端自己签发的会话或令牌。三者的所有权边界互不重叠,任何一方失效都会表现成"用户明明登录过,却被要求再输一次密码"。更糟的是,这三处往往由三个团队维护,排查时互相甩锅。

传统做法的代价正在放大。把 JWT 塞进 localStorage,等于把长期凭据暴露给任何一处 XSS;依赖第三方 Cookie 做静默 SSO,在浏览器分区存储与 SameSite 策略收紧后成片失效;手写自动填充逻辑去猜哪个输入框是用户名,结果把密码填进了注册表单。这些都不是偶发 bug,而是架构层面的必然。

1.1 三个典型症状

  • 重复登录:同一 registrable domain 下的多个子应用各自维护会话,一次跳转就触发重新认证,用户体感是"这个站老让我登录"。
  • 静默登录失效:依赖 iframe 或第三方 Cookie 的 SSO 探测被拦截后,IdP 明明有会话却拿不到断言,只能降级成整页重定向,白跳一次。
  • 自动填充错乱:浏览器无法区分登录、注册、改密三种表单,密码管理器把旧密码写进新密码字段,用户被迫手动清理。

1.2 为什么现在更值得讨论

  • FedCM 进入稳定期:Chrome 与 Edge 已把联合凭据管理做成标准通道,Safari 与 Firefox 在跟进,跨站登录第一次有了不依赖第三方 Cookie 的协议层方案。
  • 通行密钥快速普及:WebAuthn 的 PublicKeyCredential 与条件式自动填充让"无密码"从概念变成默认路径,密码管理器与网站被绑到同一套凭据模型上。
  • 第三方 Cookie 退场:所有"用 Cookie 维持登录态"的方案被迫重新设计所有权边界,Credential Management 是少数被浏览器主动推进的替代通道。

二、API 全景:四个接口各管一段

理解这套 API 的关键,是把它看成四个职责清晰的接口,而不是一堆零散方法。

2.1 PasswordCredential:让浏览器替你存密码

提交登录表单后调用 navigator.credentials.store(),把 id 与 password 交给密码管理器。下次进入登录页,用 get() 取回,浏览器自己处理自动填充与更新。它替代的是"把密码明文写进 localStorage"这种明确的安全反模式,也让用户换设备时凭据能跟着浏览器账号走。

2.2 FederatedCredential 与 FedCM

旧的 FederatedCredential 只需 provider 与 id,浏览器在 get() 时向 provider 换取令牌。FedCM 把流程标准化:IdP 提供 configURL 与 clientId,浏览器按协议拉取配置、展示账号选择器、再向 IdP 的 token 端点换取 id_token 或 access token。RP 不再需要自己嵌 iframe 猜会话。

2.3 PublicKeyCredential:把密码换成密钥对

create() 让 authenticator 生成密钥对,私钥不出设备,公钥注册到服务端;登录时 get() 用服务端下发的 challenge 做签名,天然防重放。配合 mediation: 'conditional',通行密钥会直接出现在原生自动填充 UI 里,用户点一下即完成认证。

2.4 mediation 语义与 preventSilentAccess

mediation 决定 UX 与隐私级别:silent 不弹窗,取不到就返回 null;optional 有可用户交互的凭据才弹;required 一定弹窗;conditional 把请求交给自动填充 UI。preventSilentAccess() 用于登出后显式禁止静默取凭据。用错语义的后果要么是静默失败,要么是无谓打扰。

三、最小可运行实现

下面这段代码覆盖三条主路径:存密码、FedCM 取联合凭据、条件式取通行密钥。注意 get() 一律返回 Credential | null,必须处理 null 分支。

// 1) 登录成功后,把密码交给浏览器密码管理器
async function savePassword(form) {
  const cred = new PasswordCredential({
    id: form.username.value,
    password: form.password.value,
    name: form.username.value,
  });
  await navigator.credentials.store(cred);
}

// 2) FedCM:让浏览器向 IdP 换取联合身份断言
async function federatedLogin() {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example.com/.well-known/fedcm.json',
        clientId: 'webapp-client-id',
        nonce: crypto.randomUUID(),
      }],
    },
  });
  if (!cred) return null;
  return fetch('/api/session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: cred.token }),
  });
}

// 3) 条件式自动填充:通行密钥直接进入原生 UI
async function passkeyAutofill() {
  const cred = await navigator.credentials.get({
    mediation: 'conditional',
    publicKey: {
      challenge: Uint8Array.from(window.atob(SERVER_CHALLENGE), c => c.charCodeAt(0)),
      rpId: 'example.com',
      userVerification: 'preferred',
      timeout: 60000,
    },
  });
  return cred; // 命中则是一个 PublicKeyCredential
}

服务端要做的不是"相信浏览器说已登录",而是校验 challenge 签名与 token 签名,再把 credential id 与会话绑定。

四、安全协作:浏览器、IdP 与 RP 的边界

4.1 Origin 与 Secure Context

整套 API 只在安全上下文可用,也就是全站 HTTPS,本地 localhost 除外。WebAuthn 的 rpId 必须等于或匹配当前 origin 的 registrable domain,写错会直接抛 SecurityError。FedCM 的 clientId 与 redirect 配置由 IdP 侧声明,RP 不能自报身份。跨域调用凭据接口时,浏览器按 origin 隔离存储,子域之间默认不共享。

4.2 令牌、Cookie 与点击劫持

id_token 与 access token 的正确归宿是内存或 HttpOnly Cookie,绝不能落 localStorage。FedCM 的账号选择器由浏览器绘制,天然规避点击劫持;而传统 iframe 式静默 SSO 必须校验 X-Frame-Options 或 CSP 的 frame-ancestors,否则攻击者能用透明层诱导点击。SameSite 与分区存储策略直接决定静默登录是否可用,设计阶段就要把"第三方上下文取不到 Cookie"当成常态。

4.3 用户同意与隐私语义

required 必然弹窗,适合敏感操作;optional 只在已有可用凭据时弹,适合普通登录;silent 完全不弹,适合后台静默续期,但失败时必须安静降级,不能报错打扰。服务端应记录每次凭据使用的 consent 上下文与 credential id,支持用户在 IdP 侧撤销后同步失效本地会话。

五、常见坑与排查清单

  • FedCM 拿不到账号:先确认 configURL 可达且返回正确 JSON,clientId 与 IdP 注册一致,IdP 会话 Cookie 未被 SameSite 或分区策略拦截。
  • 条件式自动填充不出现:必须 mediation: 'conditional' 且 allowCredentials 留空,用户已保存通行密钥,且页面在 HTTPS 下。
  • 密码存不进去:登录表单缺少正确的 autocomplete="username" 与 autocomplete="current-password",或 store() 前表单已被脚本移除。
  • Safari 上静默登录失败:Safari 对 FedCM 支持有限,需要保留整页重定向的传统 SSO 作为降级路径。
  • 登出后仍自动登录:只清了服务端会话,却忘了 preventSilentAccess(),或凭据仍被浏览器缓存。
  • RP ID 报 SecurityError:rpId 写了带端口或带协议的完整 URL,必须只写 registrable domain。

六、落地建议与兼容性策略

特性探测优于 UA 嗅探。用 window.PasswordCredential、window.PublicKeyCredential 与 'conditional' in CredentialMediationRequirement 做能力判断,UA 字符串在跨浏览器上不可靠。

采用分层降级:优先通行密钥,其次密码管理器自动填充,最后才回到传统表单加重定向 SSO。每层都要有独立的失败监控,避免"新接口挂了、老路径也没兜住"。

把 mediation 失败率、token 刷新失败率、凭据撤销同步延迟做成登录态健康度指标。接口上线不等于登录态收敛,真正的验收标准是用户跨子应用、跨设备、跨会话时只认证一次,且登出在所有边界同时生效。

结语

Credential Management API 的价值不在于"多一个能存密码的 API",而在于它把登录态的所有权从应用代码里拿出来,交还给浏览器与身份提供方共同托管。工程上真正的难点也在这里:你需要同时理解浏览器的隐私边界、IdP 的协议约束与服务端的会话生命周期,并在三者之间设计可降级的协作契约。把 FedCM、WebAuthn 与密码管理器当成同一套凭据体系的三个入口来建设,登录体验的收敛才成为可能。

点赞(0) 打赏

评论列表 共有 0 条评论

暂无评论
立即
投稿

微信公众账号

微信扫一扫加关注

发表
评论
返回
顶部