Skip to content

feat(auth)!: migrate WebAuthn to Passkey.#393

Open
HappyDIY wants to merge 1 commit intoOpenListTeam:mainfrom
HappyDIY:feat/upgrade_webauthn_to_passkey
Open

feat(auth)!: migrate WebAuthn to Passkey.#393
HappyDIY wants to merge 1 commit intoOpenListTeam:mainfrom
HappyDIY:feat/upgrade_webauthn_to_passkey

Conversation

@HappyDIY
Copy link

@HappyDIY HappyDIY commented Feb 23, 2026

feat(passkey)!: 迁移 WebAuthn 至 Passkey 并默认启用,统一后端 API 命名

… management

  • 迁移传统 WebAuthn 至 Passkey,支持云端同步与免用户名认证
  • 将后端所有 WebAuthn API 重命名为 Passkey,提升命名标准化程度
  • 默认启用 Passkey,以符合当前行业推广趋势
  • 在 Passkey 管理页面新增显示用户设备 IP 和 User-Agent(UA),便于设备区分
  • 新增升级流程,将旧版 WebAuthn 凭证迁移至新版 Passkey 格式
  • 在旧凭证未升级或删除前,禁止创建新的 Passkey,避免升级后的兼容性问题

Description / 描述

本次 PR 对现有 WebAuthn 认证体系进行整体升级,统一迁移至 Passkey 方案,并对相关接口与管理页面进行增强。

主要包括:

  1. 认证体系升级

    • 将传统 WebAuthn 迁移为 Passkey
    • 支持云端同步(multi-device credentials)
    • 支持免用户名输入(discoverable credentials)
  2. 接口命名标准化

    • 后端所有 webauthn 相关 API 重命名为 passkey
    • 同步更新相关调用与文档,避免语义混用
  3. 默认策略调整

    • 将 Passkey 设置为始终启用
    • 简化认证流程,统一安全策略
  4. 管理页面增强

    • Passkey 管理页面新增设备 IP 与 User-Agent 展示
    • 提升多设备场景下的可识别性与可管理性
  5. 旧凭证升级机制

    • 新增“升级”按钮,引导用户将旧版 WebAuthn 凭证升级为新版 Passkey
    • 若存在未升级的旧凭证:
      • 禁止创建新的 Passkey
      • 允许通过“升级”或“删除旧凭证”解除限制

Motivation and Context / 背景

随着主流科技公司全面推广 Passkey 体系,传统 WebAuthn 命名与使用方式已逐步过时。

本次升级解决以下问题:

  • 提升跨设备认证体验(支持云端同步)
  • 支持无用户名输入登录流程
  • 统一后端 API 命名,降低维护成本
  • 避免系统中长期并存两套凭证体系
  • 防止版本升级后旧凭证与新流程不兼容

Closes #XXXX


How Has This Been Tested? / 测试

  • 本地环境验证:
    • 新用户注册与创建 Passkey 流程
    • 免用户名登录流程验证
  • 旧用户升级验证:
    • 存在旧 WebAuthn 凭证时升级流程测试
    • 未升级时创建新 Passkey 限制验证
    • 删除旧凭证后恢复创建能力验证
  • 多设备测试:
    • 不同浏览器 / 不同设备下创建与识别测试
  • API 回归测试:
    • 重命名接口的调用路径验证
    • 文档同步检查

Checklist / 检查清单

  • I have read the CONTRIBUTING document.
    我已阅读 CONTRIBUTING 文档。
  • I have formatted my code with go fmt or prettier.
    我已使用 go fmtprettier 格式化提交的代码。
  • I have added appropriate labels to this PR (or mentioned needed labels in the description if lacking permissions).
    我已为此 PR 添加了适当的标签(如无权限或需要的标签不存在,请在描述中说明,管理员将后续处理)。
  • I have requested review from relevant code authors using the "Request review" feature when applicable.
    我已在适当情况下使用"Request review"功能请求相关代码作者进行审查。
  • I have updated the repository accordingly (If it’s needed).
    我已相应更新了相关仓库(若适用)。

Copy link
Member

@ILoveScratch2 ILoveScratch2 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

请不要进行功能无关的改动

@HappyDIY
Copy link
Author

有点关系吧,修改成 passkey 可以把密钥保存在云端,登录的时候无需输入用户名,更加方便。

@ILoveScratch2
Copy link
Member

有点关系吧,修改成 passkey 可以把密钥保存在云端,登录的时候无需输入用户名,更加方便。

我的意思是,不要进行对 Issue 模板, DOCTYPE 大小写,末尾逗号等 与你这个PR要实现的功能无关的改动

@HappyDIY
Copy link
Author

哦知道了这就改

… management

- Migrate traditional WebAuthn to Passkey to support cloud synchronization and username-less authentication
- Rename all backend WebAuthn APIs to Passkey for improved standardization
- Enable Passkey by default to align with current industry adoption trends
- Display user device IP and User-Agent (UA) in Passkey management page for better device identification
- Add upgrade flow to migrate legacy WebAuthn credentials to new Passkey format
- Prevent creation of new Passkeys until legacy credentials are upgraded or removed to avoid post-upgrade incompatibility
@HappyDIY HappyDIY force-pushed the feat/upgrade_webauthn_to_passkey branch from 7fd464b to 095ce1f Compare February 23, 2026 16:07
@HappyDIY
Copy link
Author

改好了,重新用 commit --amend 合并了一下。是因为 Prettier 格式化代码导致的。话说你们不是要求要格式化吗?这不是起到反作用了吗?

@jyxjjj
Copy link
Member

jyxjjj commented Feb 23, 2026

两回事,你这是功能,格式化是标准,如果有大量的格式化异常可能会有成员单独提交格式化PR。主要是一事一PR原则。

另外,我不认为你的改动是合理的,首先默认启用不让禁用就很不合理,其次Passkey从来不是WebAuthN的替代,而是实现,我认为你的理解就已经不对了,至少我没有找到哪个官方说法认为是替代。WebAuthN是标准,基于FIDO2标准并专用于Web的子标准,子规范,Passkey只是简化一些流程,这部分你说的没问题,但应该不会是替代。

第三,不是所有东西都已经支持Passkey,不支持的情况下应回退。这一点我不确定,因为没有具体测试(而且在我看来Passkey的安全性不如Yubico Yubikey,甚至不如Google Titan Key)。有个可能的猜测,不支持的情况下会自动回退硬件密钥。--但可以确认的是,目前为止支持的情况下可选择拒绝使用Passkey而输入硬件密钥。

@HappyDIY
Copy link
Author

@jyxjjj 感谢你这么细地 review,我补充澄清下我这边想做的事情:

  1. 关于“Passkey 不是 WebAuthn 的替代”
    这点我完全同意。Passkey 说到底还是 WebAuthn/FIDO2 体系里的一个更产品化的叫法,前端照样是走 navigator.credentials.*,并不是跳出了 WebAuthn。
    我这次更多是在“默认形态”上做调整:从以前偏 non-discoverable往 discoverable credentials 迁移,也就是现在说的 Passkey:可以免用户名、能用 conditional UI,并且有云同步这些能力。

  2. 为什么 residentKey 要用 'required'
    主要是为了把“免用户名的 passkey 体验”做实:如果创建阶段不请求可发现凭据,那后面就很难实现真正的 passkey 登录流程。
    而且 'required' 在不支持时会直接抛 NotSupportedError,不会默默给你创建一个“看起来成功但其实不是 passkey”的凭据。
    目前主流产品(Microsoft / Google / GitHub / Telegram 之类)也基本是这个方向:Passkey 放到登录主流程,传统 WebAuthn 形态更多当 2FA 或 legacy fallback。

  3. 兼容性/回退(你提醒的“不是所有东西都支持 passkey”)
    这个点我认同,也愿意补齐。我倾向加一个更温和的 fallback:

  • 注册/升级阶段:如果 residentKey='required' 触发 NotSupportedError / ConstraintError,就自动降级到 residentKey='preferred'(或者走旧的 username + allowCredentials 流程),并把这种凭据标成 legacy security key;
  • 登录阶段:继续优先走 passkey(allowCredentials 为空 + conditional UI),不支持或失败就回退到传统登录/legacy key。
    这样老设备、老安全密钥都还能用,Passkey 只是默认优先级更高。
  1. 默认启用但不能禁用
    我可以把开关补回来:但是默认开启但允许管理端关闭;关掉后就彻底不触发 passkey 的自动/conditional 流程。

如果你觉得上面这套方向 OK,我就补一个 commit。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants