使用@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 浏览器样式__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

配置主机应用程序一次

在__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: 主要的HTTPS依赖方源，用于 shim 和直接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 元数据和由清单使用的生成资源

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

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

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注意事项

在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教程