使用 @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 保持相同的 WebAuthn 流程，已经在 Web 上使用：

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: __CAPGO_KEEP_0__ 的依赖方主机名
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 可以与您的网站共享同一个依赖方和 passkeys，当数字资产链接配置时，但本机断言源站与浏览器源站不相同。如果您的后端严格验证 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 的实现细节入门指南了解如何在 Getting Started 中实现 @capgo/capacitor-social-login 了解如何在 @capgo/capacitor-social-login 中实现 @capgo/capacitor-native-biometric 了解如何在 @capgo/capacitor-native-biometric 中实现两步验证了解如何在两步验证中实现

Passkey

Passkey 指南