通行密钥 Capacitor 插件

使用 @capgo/capacitor-passkey

在 Capacitor 应用中保留浏览器风格的 WebAuthn code，同时由插件处理原生 passkey 调用和原生宿主补丁。

浏览器风格的 API

@capgo/capacitor-passkey 沿用您在 Web 端已经在用的 WebAuthn 流程：

await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });

在原生构建中，该插件会安装一个 shim 来 navigator.credentials.create() 以及 navigator.credentials.get()将请求转发至 iOS 和 Android 的 passkey API，并向您的 App 返回类似浏览器的凭据对象。

安装并同步原生项目

bun add @capgo/capacitor-passkey
bunx cap sync

配置一次宿主 App

在以下位置添加插件配置 capacitor.config.ts 或 capacitor.config.json:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'app.capgo.passkey.example',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorPasskey: {
      origin: 'https://signin.example.com',
      autoShim: true,
      domains: ['signin.example.com'],
    },
  },
};

export default config;

插件配置的作用

配置读取自 plugins.CapacitorPasskey 中的 capacitor.config.*.

• origin：shim 和直接 API 使用的主要 HTTPS relying-party origin
• domains: 在同步期间将其补丁到原生配置中的额外 relying-party 主机名
• autoShim: 默认为 true 并控制原生 cap sync 自动配置钩子

修改配置后请再次运行 sync：

bunx cap sync

在启动阶段安装 shim

从标准包入口导入插件，然后在应用启动期间安装 shim：

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

await CapacitorPasskey.autoShimWebAuthn();

之后，您现有的浏览器风格 passkey code 可以保持不变。

如果需要在运行时强制使用 shim 或覆盖已配置的 origin，请调用：

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

CapacitorPasskey.shimWebAuthn({
  origin: 'https://signin.example.com',
});

保留原有的 WebAuthn 流程

const credential = await navigator.credentials.create({
  publicKey: registrationOptions,
});

const assertion = await navigator.credentials.get({
  publicKey: requestOptions,
});

同步补丁能为你做什么

在...期间 bunx cap sync，该插件会更新生成的原生宿主项目：

• iOS：按需配置 associated domains 权限和 Xcode entitlements
• Android： asset_statements 用于 manifest 的元数据及生成的资源

原生配置仍需网站信任文件

该插件减少了 App 端的工作量，但 Passkey 仍依赖你 Relying Party 域名的网站信任文件。你仍需托管：

• https://your-domain/.well-known/apple-app-site-association
• https://your-domain/.well-known/assetlinks.json

插件可以在 sync 期间修补生成的原生项目，但无法替你创建或托管这些网站信任文件。

其他公开方法

公开插件 API 还暴露了定义在以下位置的直接辅助函数： src/definitions.ts:

• await CapacitorPasskey.getConfiguration() 返回解析后的 origin, domains, autoShim，以及当前的 platform.
• await CapacitorPasskey.createCredential(...) 通过 JSON 安全的 WebAuthn payload 注册 Passkey。
• await CapacitorPasskey.getCredential(...) 通过 JSON 安全的 WebAuthn payload 使用现有的 passkey 进行身份验证。
• await CapacitorPasskey.isSupported() 报告当前运行时环境是否支持 passkeys。
• await CapacitorPasskey.getPluginVersion() 返回当前原生实现的版本标识。

平台指南

• 入门指南
• iOS 配置
• Android 配置
• 后端注意事项

iOS 重要说明

在 iOS 17.4 及更高版本中，该插件使用浏览器风格的 client-data API，因此配置的 HTTPS origin 会反映在 clientDataJSON.

Android 重要注意事项

配置 Digital Asset Links 后，Android Credential Manager 可以与您的网站共享相同的 relying party 和 passkeys，但原生断言 origin 与浏览器 origin 并不完全相同。如果您的后端严格校验 clientDataJSON.origin，请确保它同时接受你的网站 Origin 和 Android 应用 Origin。

完整参考

• GitHub: https://github.com/Cap-go/capacitor-passkey/
• 文档：/docs/plugins/passkey/

继续阅读：使用 @capgo/capacitor-passkey

如果你正在使用 使用 @capgo/capacitor-passkey 用来规划身份验证和账户流程，并将它与 @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， 快速入门 有关“入门指南”中的实现细节， @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-native-biometric 以及 @capgo/capacitor-native-biometric 中的实现细节， 双因素认证 有关双重身份验证的实现细节。