Ente 账号 PasskeysWebAuthn二次验证完全指南启用、登录与恢复【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/entePasskeys 是基于设备内置强密码学如 Windows Hello、Apple Touch ID的新一代身份验证机制也是 WebAuthnWeb Authentication凭据的通俗叫法。本文围绕 Ente 官方文档 docs/docs/photos/features/account/passkeys.md 展开结合仓库中的服务端 Go 实现server/pkg/repo/passkey/passkey.go、server/pkg/controller/passkeys.go与数据库迁移脚本完整讲解如何将 Passkeys 作为 Ente 账号的第二因素2FA使用包括与 TOTP 的关系、启用/停用、新设备登录流程以及丢失硬件密钥时的恢复路径。Passkeys 是什么为什么 Ente 用它做 2FAPasskeys 是 W3C WebAuthn 标准的产物本质上是一组绑定到特定「依赖方Relying PartyRP」的加密凭据。与传统密码不同私钥永远不会离开你的设备登录时系统通过生物识别指纹、面容或硬件安全密钥如 Yubikey解锁私钥完成签名从而在防钓鱼的同时提供极高的安全性。Ente 将其引入为账号的第二因素而不是替代密码。官方文档明确指出You can use passkeys as a second factor to secure your Ente account.也就是说在你的 Ente 账号中Passkeys 扮演的角色是「登录时的二次验证」与下面要讲的 TOTP 并列。从服务端源码看Ente 使用 Go 生态的 go-webauthn/webauthn 库实现完整协议流程见 server/pkg/repo/passkey/passkey.go 中的newWebAuthnInstance其中配置了 RP 显示名Ente、RPID、允许的 RP Origin 以及超时策略登录Login挑战强制超时 2 分钟注册Registration挑战强制超时 5 分钟。这两处超时由服务端强制校验Enforce: true过期后凭据验证会直接失败防止挑战被无限期重放。Passkeys 与 TOTP 的关系Ente 早已支持 TOTP 验证码官方甚至独立开发了一款 Ente Auth 应用 用于存储它们。Passkeys 是作为 TOTP 的替代方案引入的第二因素机制。文档中的关键行为约定只有一条但非常重要If you add a passkey to your Ente account, it will be used instead of any existing 2FA codes that you have configured (if any).即一旦账号中新增了 Passkey登录时的第二因素就由 Passkey 接管替代之前配置的任何 TOTP 验证码若存在。这个优先级逻辑同样体现在服务端登录响应结构里——server/ente/user.go 中的EmailAuthorizationResponse同时返回PasskeySessionID、TwoFactorSessionID与TwoFactorSessionIDV2三个字段注释明确写道TwoFactorSessionIDV2 is set only if user has both passkey and two factor enabled. This is to ensure older clients keep using passkey flow when both are set.也就是说当用户同时启用 Passkey 和 TOTP 时服务端会优先引导客户端走 Passkey 流程旧版客户端也能平滑兼容。启用与停用 PasskeysPasskeys 的启用/停用规则非常直观完全由「账号中是否存在 Passkey」决定启用向账号添加一个或多个PasskeyPasskey 2FA 即自动生效停用删除账号中全部 PasskeyPasskey 2FA 即自动关闭。管理入口在 Ente 客户端应用的设置菜单中找到PasskeyPasskey选项点击后会打开 Ente Accounts Web 应用accounts.ente.com在那里可以添加新的 Passkey重命名已有的 Passkey自定义友好名称friendlyName删除不再使用的 Passkey。服务端为这些操作提供了完整的 REST API集中在 server/pkg/api/passkeys.goHTTP 方法路径作用GET/passkeys列出当前账号全部 Passkey并返回对应的 Accounts URLPOST/passkeys/begin-registration开始注册挑战返回 CredentialCreation options 与 sessionIDPOST/passkeys/finish-registration完成注册写入新凭据PATCH/POST/passkeys/{passkeyID}/rename重命名 Passkey通过friendlyName查询参数DELETE/passkeys/{passkeyID}删除指定 Passkey对应的控制器逻辑在 server/pkg/controller/passkeys.go其中有几个值得注意的约束每个账号最多 10 个 Passkey常量MaxPasskeys 10定义于 server/ente/passkey.go注册时若已达上限服务端会返回ErrMaxPasskeysReached友好名称长度限制friendlyName必须在 1256 个字符之间_passKeyNameMaxLength 256否则返回400 Bad Request删除是软删除执行的是UPDATE passkeys SET deleted_at ...见 server/pkg/repo/passkey/passkey.go便于审计与恢复。账号数据中的 Passkey 计数在获取用户详情时服务端会统计该账号当前有效的 Passkey 数量并返回给客户端字段passkeyCount见 server/pkg/controller/user/user_details.go 与 server/ente/user.go。客户端据此可以在设置页直观展示「已启用 N 个 Passkey」之类的状态。关于旧域名 accounts.ente.io 的迁移说明官方文档特别提示Ente Accounts has moved from accounts.ente.io to accounts.ente.com. Older passkeys created on the old domain continue to work, and Ente will automatically open the right domain for your account. New passkeys are created on accounts.ente.com.服务端为此实现了完整的双 RPID 兼容。在 server/pkg/repo/passkey/passkey.go 的NewRepository中会同时读取webauthn.rpid与webauthn.legacy-rpid两个配置分别初始化当前与旧版 WebAuthn 实例并通过AccountsURLForUser同文件 L164-L173根据用户既有凭据所属的 RPID 自动选择返回accounts.ente.com还是accounts.ente.io。对应配置项见 server/configurations/local.yamlapps: accounts: # 默认 https://accounts.ente.com accounts-legacy: # 默认 https://accounts.ente.io仅用于旧版 passkey 迁移数据库层面迁移 server/migrations/122_passkey_rp_ids.up.sql 为passkey_credentials与webauthn_sessions增加了rp_id列无rp_id的旧凭据会被视为属于 legacy RPID见 local.yaml L311-L312 的注释说明。使用 Passkey 登录新设备Passkey 2FA 启用后流程如下你在新设备上登录 Ente 账号输入邮箱/密码完成第一步Ente Accounts Web 应用自动打开浏览器按自身与设备的提示引导你完成 Passkey 验证验证方式与你创建该 Passkey 时所用机制一致——扫描二维码、按指纹、在 Yubikey 或其他安全密钥硬件上按键等不同浏览器/设备的提示文案有差异但机制一致验证通过登录继续获得会话凭证。从源码角度看登录阶段的 2FA 验证依赖passkey_login_sessions表迁移见 server/migrations/76_add_passkey_login_sessions.up.sql服务端在该表中记录user_id、session_id、创建时间与过期时间。相关方法AddPasskeyTwoFactorSession、GetUserIDWithPasskeyTwoFactorSession、StoreTokenData、GetTokenData位于 server/pkg/repo/passkey/passkey.go其中对令牌获取做了三重用例约束会话必须已完成验证verified_at非空否则返回SESSION_NOT_VERIFIED验证后的令牌仅在2 分钟内可获取TokenFetchAllowedDurationInMin 2超时返回INVALID_SESSION每个会话最多只能获取2 次令牌MaxSessionTokenFetchLimit 2防止令牌被反复拉取。仓库还专门为这类会话写了单元测试例如 server/pkg/repo/passkey/passkey_test.go 中的TestStoreTokenDataRoundTripsLegacyNULByte验证了含 NUL 字节的旧式密钥材料在StoreTokenData往返过程中不被破坏保障旧凭据的兼容性。凭据的存储形态注册完成后服务端将 WebAuthn 凭据序列化入库模型定义在 server/ente/passkeyCredential.gocredential_id凭据 IDBase64public_key公钥Base64 编码的字节数组attestation_type认证器证明类型authenticator_transports逗号分隔的传输方式列表如usb,nfc,ble,internalcredential_flags、authenticatorJSON 编码的结构体含 AAGUID、SignCount、CloneWarning 等。对应建表 SQL 见迁移 server/migrations/75_add_passkeys.up.sql其中passkeys表存放用户可见的 Passkey 元信息friendly_name、deleted_atpasskey_credentials表存放底层加密凭据webauthn_sessions表存放注册/登录挑战会话challenge 唯一、含过期时间。读取时由WebAuthnCredential()passkeyCredential.go L28-L89反序列化回标准webauthn.Credential参与签名校验。一个实现细节可发现凭据Discoverable Credentials在 server/pkg/repo/passkey/passkey.go 中可以看到一个特例当用户邮箱以ente.io或ente.com结尾时注册阶段会强制要求 Resident KeyResidentKeyRequirementRequired。注释解释这是为了让 Android 端能够向第三方密码管理器提供 Passkey 支持——这属于 Ente 官方账号的定制行为普通自托管实例的用户走默认注册流程。恢复丢失 Passkey 后如何找回账号如果你因为丢失硬件密钥等原因无法再用 Passkey 登录官方提供的恢复路径是登录时在弹出的 Passkey 验证对话框中按下取消在随后出现的错误提示中选择「Recover two-factor」恢复双因素验证选项进入恢复页面后输入你的Ente recovery key恢复密钥完成登录登录成功后前往Passkey页面删除丢失的 Passkey并按需添加新 Passkey。服务端为这套恢复流程提供了对应接口。在 server/ente/passkey.go 中SetPasskeyRecoveryRequest要求同时提交secret恢复密钥userSecretCipher/userSecretNonce用恢复密钥加密的 user secret 密文与随机数。源码注释解释了这样设计的用意The skip secret encrypted with the recovery key. Decrypting it during MFA recovery proves possession of that key.即在恢复阶段对密文成功解密就等价于向服务端证明了「用户确实持有恢复密钥」从而可以跳过 Passkey 这一因素继续登录。TwoFactorRecoveryStatus结构则向外暴露了当前账号是否允许管理员重置、以及是否启用了 Passkey 恢复等状态server/ente/passkey.go。注意恢复密钥是你账号加密体系的最后一道保险。若 Passkey 与恢复密钥同时丢失则无法自行恢复账号需要联系官方支持supportente.com寻求人工帮助。因此建议在启用 Passkey 2FA 的同时妥善离线备份恢复密钥。自托管时如何配置 Passkey 支持Passkey 属于可选能力配置段位于 server/configurations/local.yaml 的webauthn与apps部分apps: accounts: # 你的 accounts Web 应用地址用于 passkey 2FA 与跨应用流程默认 https://accounts.ente.com accounts-legacy: # 可选仅用于旧版 rp_id 的 passkey 迁移 webauthn: # 依赖方Relying PartyID决定了凭据的作用域。见 W3C WebAuthn 规范 rp-id rpid: localhost # 允许发起 WebAuthn 请求的 Origin 白名单 rporigins: - http://localhost:3001 # 可选。仅当需要迁移旧 RPID 下的 passkey 时配置普通部署请留空。 # 错误的 RP/Origin 会导致用户无法使用已有 passkey。 # 没有 rp_id 的凭据会被视为属于 legacy-rpid其用户继续使用 apps.accounts-legacy。 legacy-rpid: legacy-rporigins: []配置要点webauthn.rpid必须与部署域名的实际 Origin 严格匹配因为它直接决定生成凭据的作用域W3C 规范中的 rp-id 语义webauthn.rporigins是服务端校验请求来源的白名单防止跨站伪造 WebAuthn 请求只有当你确实有accounts.ente.io时代的存量 Passkey 需要迁移时才需要设置legacy-rpid/legacy-rporigins且必须保证旧凭据所属的 rp_id 与配置完全一致——代码在legacyRPIDForUserpasskey.go L733-L758中会强制校验rp_id 不匹配会直接报错避免凭据被错误作用域污染。常见问题FAQ官方文档关联了两个账号相关 FAQ分别对应 Passkey 的两个高频疑问能否用 Passkey 替代密码在 Ente 中Passkey 目前定位为第二因素而非替代密码。密码配合密钥派生仍是账号加密体系的主认证方式Passkey 负责登录时的二次验证。丢失 Passkey 会怎样见上文「恢复」一节使用 Ente 恢复密钥即可重新登录并清理/更换 Passkey若恢复密钥也丢失则需联系官方支持人工处理。小结Passkeys 为 Ente 账号提供了比 TOTP 更抗钓鱼、体验更顺滑的第二因素方案添加即启用、清空即停用新设备登录时 Accounts Web 应用自动引导验证丢失硬件后可通过恢复密钥完成自救。服务端实现go-webauthn 集成、双 RPID 兼容、passkey_login_sessions会话与令牌限制、软删除与凭据序列化与数据库迁移75、76、122共同保证了这一流程的安全性与兼容性。对自托管用户而言正确配置webauthn.rpid与rporigins是 Passkey 2FA 可用性的关键前提。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考