Using @capgo/capacitor-passkey

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

ブラウザスタイルのAPI

@capgo/capacitor-passkey __CAPGO_KEEP_0__はすでにウェブで使用しているWebAuthnのフローを維持します:

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

ネイティブビルドの場合、プラグインは navigator.credentials.create() 、iOSとAndroidパスキーアイピーへのリクエストを転送し、ブラウザライクのクレデンシャルオブジェクトをアプリに返します。 navigator.credentials.get(), forwards the request to iOS and Android passkey APIs, and returns browser-like credential objects to your app.

ネイティブプロジェクトをインストールして同期する

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: ネイティブ設定に同期中にパッチする追加の依存先ホスト名
autoShim: 初期値は true とネイティブの自動構成ハックを制御する cap sync __CAPGO_KEEP_0__

設定を変更した後は、再度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,
});

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中のときに修正できますが、ウェブサイトの信頼ファイルを作成またはホストすることはできません。

その他のパブリックメソッド

パブリックプラグイン API も、定義されている直接ヘルパーを公開します。 src/definitions.ts:

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

プラットフォームガイド

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に関するチュートリアル