使用@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，并将浏览器样式的凭据对象返回给您的应用。

安装和同步本机项目

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: primary HTTPS relying-party origin used by the shim and direct 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 元数据和由清单使用的生成资源

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

The plugin reduces app-side work, but passkeys still depend on the website trust files for your relying-party domain. You still need to host:

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

The plugin can patch the generated native projects during sync, but it cannot create or host those website trust files for you.

其他公共方法

The public plugin API also exposes the direct helpers defined in 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, 和 Two-factor authentication 为 Two-factor authentication 的实施细节。

Passkey

关于Passkey的教程