使用 @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 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: 主要 HTTPS 依赖方源用于 shim 和直接 API
domains: 需要修补到本地配置的额外依赖方主机名
autoShim: 默认值 true 和控制本地 cap sync 自动配置钩子

更改配置后再次运行同步:

bunx cap sync

在引导期间安装 shim

从标准包入口点导入插件，然后在应用引导期间安装 shim:

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

await CapacitorPasskey.autoShimWebAuthn();

然后，您的现有浏览器样式 passkey 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,
});

What sync patches for you

在 bunx cap sync当

插件更新生成的本机主机项目:
iOS: 当需要时，相关域名特权和 Xcode 特权编程 asset_statements Android:

元数据和由清单文件使用的生成资源

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

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

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

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

The public plugin API also exposes the direct helpers defined in src/definitions.ts:

await CapacitorPasskey.getConfiguration() 公共插件 __CAPGO_KEEP_0__ 也暴露了在 "returns the resolved" 中定义的直接助手 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 可以与您的网站共享同一个依赖方和密钥，当数字资产链接配置时，但原生断言源不相同于浏览器源。如果您的后端严格验证 clientDataJSON.origin

详细参考

GitHub: https://github.com/Cap-go/capacitor-passkey/
文档: /docs/plugins/passkey/

Passkey

Passkey 的教程