使用@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() 并将请求转发到iOS和Android Passkey API，并将浏览器样式的凭据对象返回给您的应用。 navigator.credentials.get()并

安装并同步本机项目

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 清单和由清单使用的生成资源

原生设置仍然需要网站信任文件

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

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(...) 使用一个现有的 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/

Passkey

关于Passkey的教程