使用@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 保持您在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

配置主机应用程序一次

在插件配置中添加__CAPGO_KEEP_0__ 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 依赖方源
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(...) 使用现有的 passkey 从 JSON 安全的 WebAuthn payload 中进行身份验证。
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教程