使用@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

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

其他公共方法

Capacitor 公开插件 API 还暴露了在 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凭据管理器可以与您的网站共享同一个依赖方和密钥，当数字资产链接配置时，但原生断言源与浏览器源不相同。如果您的后端严格验证 clientDataJSON.origin请确保接受Android应用源和您的网站源

完整参考

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的实现细节，双因素认证查看双因素认证的实现细节

Passkey

Passkey教程