使用 @capgo/capacitor-passkey

Keep your browser-style WebAuthn code in a Capacitor app while the plugin handles native passkey calls and native host patching.

浏览器样式 API

@capgo/capacitor-passkey 浏览器样式 __CAPGO_KEEP_0__ 保持您在 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，返回应用程序的浏览器样式凭据对象。

安装并同步本机项目

bun add @capgo/capacitor-passkey
bunx cap sync

配置主应用一次

在 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: 主应用的HTTPS依赖方原点，用于 shim 和直接API
domains: 需要在本地配置中进行补丁的额外依赖方主机名
autoShim: 默认值 true 并控制本地 cap sync 自动配置钩子

更改配置后，请再次运行同步：

bunx cap sync

在引导期间安装 shim

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

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

await CapacitorPasskey.autoShimWebAuthn();

然后，您的现有浏览器样式 code 可以保持不变。

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

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：相关域名权限和 Xcode 权限编程时需要
Android： asset_statements 元数据和由清单使用的生成资源

本机设置仍然需要网站信任文件

该插件减少了应用侧的工作，但仍然依赖于您的依赖方域的网站信任文件。您仍然需要托管:

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

该插件可以在同步期间修复生成的本机项目，但无法为您创建或托管这些网站信任文件。

其他公共方法

公共插件 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 提示

在 iOS 17.4 及以上版本中，插件使用浏览器风格的客户端数据 API，因此配置的 HTTPS 源将反映在 clientDataJSON.

重要 Android 警告

Android Credential Manager 可以与您的网站共享同一个依赖方和密钥，当数字资产链接配置时，但原生断言源与浏览器源不相同。如果您的后端严格验证 clientDataJSON.origin请确保接受 Android 应用程序源和您的网站源。

完整参考

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

继续使用@capgo/capacitor-passkey

如果您正在使用 使用@capgo/capacitor-passkey 与@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-passkey 查看@capgo/capacitor-passkey, for the implementation detail in @capgo/capacitor-passkey, 查看开始使用, @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login 查看@capgo/capacitor-social-login, @capgo/capacitor-native-biometric 查看@capgo/capacitor-native-biometric, for the implementation detail in @capgo/capacitor-native-biometric, and 双因素认证双因素认证的实现细节。

Passkey

Passkey 的教程