Capacitorで@capgo/capacitor-passkeyを使用する

Keep your browser-style WebAuthn code in a Capacitor app while the plugin handles native passkey calls and native host patching.

Browser-style API

@capgo/capacitor-passkey ブラウザで使用しているWebAuthnの流れを同じに保ちます。

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

ネイティブビルドの場合、プラグインは navigator.credentials.create() と navigator.credentials.get()をインストールし、iOSとAndroidのPasskey APIにリクエストを転送し、ブラウザのクレデンシャルオブジェクトをアプリに返します。

nativeプロジェクトをインストールして同期する

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のリレーピアオリジン
autoShim : 同期中にnative設定にパッチするために追加するリレーピアホスト名 true : 初期値は cap sync nativeの自動設定のハックを制御します

設定を変更した後は、syncを再実行してください。

bunx cap sync

起動時に 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,
});

Capgoがsyncをどのように修正するか

プラグインは、生成されたネイティブホストプロジェクトを更新する bunx cap synciOS: 必要に応じて関連ドメインの特権とXcodeの特権のワイヤリング

Android:
メタデータと生成されたリソースがマニフェストによって使用される asset_statements メタデータと生成されたリソースがマニフェストによって使用される

ネイティブ設定では依然としてウェブサイトの信頼ファイルが必要です

プラグインはアプリ側の作業を軽減しますが、パスキーは依然としてウェブサイトの信頼ファイルに依存しています。ウェブサイトの信頼ファイルが必要なリレーピアドメインの場合、依然としてホストする必要があります。

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

プラグインは生成されたネイティブプロジェクトをSync時に修正できますが、ウェブサイトの信頼ファイルの作成やホストは行えません。

その他の公開メソッド

Capgoのプラグイン API も、WebAuthnの直接ヘルパーを定義している src/definitions.ts:

await CapacitorPasskey.getConfiguration() WebAuthnのJSONセーフペイロードから解決されたパスキーを返します。 origin, domains, autoShim現在の platform.
await CapacitorPasskey.createCredential(...) WebAuthnのJSONセーフペイロードから既存のパスキーで認証します。
await CapacitorPasskey.getCredential(...) 現在のランタイムがパスキーをサポートしているかどうかを報告します。
await CapacitorPasskey.isSupported() 現在のネイティブ実装バージョンマーカーを返します。
await CapacitorPasskey.getPluginVersion() プラットフォームガイド

The public plugin __CAPGO_KEEP_0__ also exposes the direct helpers defined in

iOSの重要な注意事項

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

Androidの重要な注意事項

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

フルリファレンス

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

パスキー

Passkeyに関するチュートリアル