Electron 与 Chrome 的 Passkey 实现差异及方案参考

在桌面端应用中，使用网页内嵌的 Passkey（WebAuthn）时，Electron 环境与标准 Google Chrome 浏览器在凭证隔离、存储策略以及跨应用共享上存在显著差异。

一、主流实现方式与限制对比（含 Electron vs Chrome 差异）

​ 通过上面的对比可以看出来，想要完全实现类似chrome的效果其实比较难，electron走在线页面主要是影响体验，所以这里对在线页面性能要求就比较高。如果选择原生，win上问题不会特别多，主要在于mac上的限制，浏览器注册在自己内部的其他应用无法读取，应用自己注册则要求iCloud 密码必须开启，这样就需要登录apple账号，在特定网络环境下限制比较多。

​ 另外一个问题必须要提及的就是mac上开发的过程中。passkey关联域名需要与应用bundleId进行绑定，https://learn.microsoft.com/zh-cn/dotnet/maui/macios/universal-links?view=net-maui-10.0 https://expo.nodejs.cn/linking/ios-universal-links/ 文章中最重要的就是两个：

​ a. 域名关联

开发者后台启用关联域:

https://learn.microsoft.com/zh-cn/dotnet/maui/macios/universal-links?view=net-maui-10.0#add-the-associated-domains-entitlement-to-your-app

修改plist文件:

https://learn.microsoft.com/zh-cn/dotnet/maui/macios/universal-links?view=net-maui-10.0#add-the-associated-domains-entitlement-to-your-app

<key>com.apple.developer.associated-domains<key>
<array>
  <string>applinks:recipe-app.com</string>
</array>

​ b. 创建关联域文件

https://learn.microsoft.com/zh-cn/dotnet/maui/macios/universal-links?view=net-maui-10.0#create-and-host-an-associated-domains-file

这个主要是在passkey关联域的服务器需要配置一个文件，必须开放外网访问，apple cdn会访问验证后缓存到本地(首次发布后需要大概24左右生效)

https://domain.name/.well-known/apple-app-site-association
服务器返回的 Content-Type 为 application/json，不要进行redirect
 
 {
  "webcredentials": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  }
}

二、Electron 版本演进与能力引入

这里为啥会提及electron的版本，主要原因还是在于electron在mac上的差异性，虽然electron的版本支持了passkey，但是由于mac钥匙串的特殊性，导致长时间mac上无法唤起touchid认证，所以这个方案变成主流了vault12/electron-webauthn-mac，electron官方也有很多issue，所以官方在目前几个版本实现了，从目前来看至少需要41.6.0

针对内置的 configureWebAuthn 方案，不同 Electron 版本的行为差异如下：

三、联调避坑与关键配置指南

在实际开发和打包过程中，需要特别注意以下几点：

1. 平台差异与环境适配 (Win vs Mac)

• macOS：需在应用配置文件（Entitlements）中正确配置 keychain-access-groups，且代码中 app.configureWebAuthn 传入的 keychainAccessGroup 必须与之保持一致（格式如：TEAMID.BUNDLEID.webauthn）。由于 macOS 的沙箱与钥匙串隔离机制，其他应用注册的 Passkey 无法被读取。
• Windows：依赖 Windows Hello 体系及相应的 TPM 硬件支持，打包和权限配置与 macOS 的 Keychain 机制不同，需确保系统已启用 WinHello(指纹、pin或者硬件USB密钥)并且运行环境满足。
• 通用环境：内置 configureWebAuthn 路径必须在正确的 HTTPS 且同源的 Origin 下运行，不能直接通过 file:// 协议加载页面。

2. 必选事件监听

主进程必须监听 select-webauthn-account 事件，否则在多账号或多凭证选择场景下会导致认证流程卡住或断言失败：

session.defaultSession.on('select-webauthn-account', (details, callback) => {
  // 选择对应凭证的逻辑
  callback(selectedCredentialId);
});

app.configureWebAuthn({
  touchID: {
    keychainAccessGroup: 'TEAMID.BUNDLEID.webauthn', // 须与 entitlements keychain-access-groups 一致
    // promptReason?: string  // 41.6+ 可覆盖弹窗文案
  }
});

3. 必选事件监听

在实际开发过程中，mac上由于校验plist的问题和运行进程的问题，修改后直接打包测试。win上没有这个限制

下面是一些相关的issue