Passkey Capacitor插件

使用 @capgo/capacitor-passkey

在浏览器样式的 WebAuthn code 中，使用一个 Capacitor 应用程序，同时插件处理本机 passkey 调用和本机主机补丁。

浏览器样式 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: 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 元数据和由清单使用的生成资源

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

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

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

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

其他公共方法

该公共插件 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 配置
• Android 配置
• 后端注意事项

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-社交登录 有关@capgo/capacitor-social-login的实现细节 @capgo/capacitor-native-biometric 有关@capgo/capacitor-native-biometric的实现细节，以及 双因素身份验证 有关双因素身份验证的实现细节