Passkey Capacitor插件

使用 @capgo/capacitor-passkey

保持您的浏览器样式WebAuthn code 在一个 Capacitor 应用程序中，而插件处理本机 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 APIs, 并将浏览器-like 凭据对象返回给您的应用。

安装并同步本机项目

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: 主要 HTTPS 依赖方源站点，用于 shim 和直接 __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,
});

Sync 为您修复了什么

在 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() 判断当前运行时是否支持密钥认证。
• 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 和 双重验证 为双重验证的实现细节