Using @capgo/capacitor-passkey

ブラウザスタイルのWebAuthn codeを、Capacitorアプリ内に保管し、プラグインはネイティブのパスキー呼び出しとネイティブホストのパッチングを処理します。

ブラウザスタイルのAPI

@capgo/capacitor-passkey __CAPGO_KEEP_0__は、既存のWeb上で使用しているWebAuthnフローを維持します。

await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });

ネイティブビルドでは、プラグインは navigator.credentials.create() と navigator.credentials.get(),iOSとAndroidのパスキー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 HTTPSの主な依存元のオリジン capacitor.config.*.

origin: API に使用される shim と直接
domains: native config にパッチするために sync に追加する extra 依存元のホスト名
autoShim: default になります true native の設定を制御します cap sync native の設定を自動で設定する hook

config を変更した後、sync を再実行してください

bunx cap sync

bootstrap の際に shim をインストールしてください

標準のパッケージエントリポイントからプラグインをインポートし、app の bootstrap の際に 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

プラグインは生成されたネイティブプロジェクトをsync中のパッチが可能ですが、ウェブサイトの信頼ファイルの作成またはホストはできません。

その他の公開メソッド

公開プラグイン API も、 src/definitions.ts:

await CapacitorPasskey.getConfiguration() 直接ヘルパーを定義している origin, domains, autoShim, そして現在の platform.
await CapacitorPasskey.createCredential(...) WebAuthn の JSON 安全なペイロードからパスキーを登録します。
await CapacitorPasskey.getCredential(...) WebAuthn の JSON 安全なペイロードから既存のパスキーで認証します。
await CapacitorPasskey.isSupported() 現在の実行環境がパスキーをサポートしているかどうかを報告します。
await CapacitorPasskey.getPluginVersion() 現在のネイティブ実装バージョンマーカーを返します。

プラットフォームガイド

iOS に重要な注意

iOS 17.4 以降では、プラグインはブラウザスタイルのクライアントデータ API を使用するため、構成された HTTPS のオリジンが反映されます。 clientDataJSON.

Androidの重要な注意事項

Android Credential Managerは、Digital Asset Linksが設定されている場合、ウェブサイトと同じ依存パーティーとパスキーを共有できますが、ネイティブのアサーションオリジンはブラウザのオリジンと同じではありません。バックエンドが厳密に検証する場合 clientDataJSON.origin

詳細なリファレンス

GitHub https://github.com/Cap-go/capacitor-passkey/
ドキュメント: /docs/plugins/passkey/

Passkey

Passkeyのチュートリアル