ガイド
Capacitor で Passkey を使用する方法
@capgo/capacitor-passkey を使用する
プラグインがネイティブの passkey 呼び出しとネイティブホストのパッチ適用を行うため、Capacitor アプリ内でブラウザスタイルの WebAuthn code を維持できます。
ブラウザ形式の API
@capgo/capacitor-passkey Webですでに使っているWebAuthnフローをそのまま維持します：
await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });
Native Buildでは、このプラグインがshimをインストールし、 navigator.credentials.create() と navigator.credentials.get()リクエストをiOS/Androidのpasskey APIに転送して、ブラウザと同様のcredentialオブジェクトをアプリに返します。
ネイティブプロジェクトのインストールと同期
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 relying-party origindomains: sync 時にネイティブ設定へパッチする追加の relying-party ホスト名autoShim: デフォルト値はtrueおよびネイティブのcap sync自動設定フック
設定変更後、再度 sync を実行してください:
bunx cap sync
ブートストラップ時に shim をインストールする
標準パッケージのエントリポイントからプラグインをインポートし、アプリのブートストラップ中に shim をインストールします:
import { CapacitorPasskey } from '@capgo/capacitor-passkey';
await CapacitorPasskey.autoShimWebAuthn();
その後、既存のブラウザ形式の passkey code はそのまま使えます。
実行時に shim を強制したり、設定済みの origin を上書きしたりする必要がある場合は、以下を呼び出します:
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: 必要に応じて associated domains entitlements と Xcode entitlements を設定
- Android:
asset_statementsメタデータ、および manifest で使用される生成リソース
ネイティブセットアップには引き続きウェブサイトの信頼ファイルが必要です
このプラグインによりアプリ側の作業は軽減されますが、パスキーは依然として Relying Party ドメインのウェブサイト信頼ファイルに依存します。以下のファイルをホストする必要があります：
https://your-domain/.well-known/apple-app-site-associationhttps://your-domain/.well-known/assetlinks.json
プラグインは sync 中に生成されたネイティブプロジェクトをパッチできますが、これらのウェブサイト信頼ファイルを代わりに作成・ホストすることはできません。
その他の公開メソッド
公開プラグイン API は、以下で定義されている直接呼び出せるヘルパーも公開しています： src/definitions.ts:
await CapacitorPasskey.getConfiguration()解決済みの値を返します：origin,domains,autoShim、および現在のplatform.await CapacitorPasskey.createCredential(...)JSON セーフな WebAuthn ペイロードからパスキーを登録します。await CapacitorPasskey.getCredential(...)JSONセーフなWebAuthnペイロードを使用して、既存のpasskeyで認証を行います。await CapacitorPasskey.isSupported()現在のランタイムがpasskeyをサポートしているかどうかを返します。await CapacitorPasskey.getPluginVersion()現在のネイティブ実装のバージョンマーカーを返します。
プラットフォーム別ガイド
iOSに関する重要な注意点
iOS 17.4以降では、このプラグインはブラウザ形式のclient-data API を使用するため、設定されたHTTPS originが clientDataJSON.
Androidに関する重要な注意点
Digital Asset Linksが設定されていれば、Android Credential Managerはウェブサイトと同じrelying partyやpasskeyを共有できますが、ネイティブのassertion originはブラウザのoriginとは異なります。バックエンドで厳密に検証している場合、 clientDataJSON.origin、ウェブサイトのオリジンに加えてAndroidアプリのオリジンも許可されていることを確認してください。
リファレンス全文
- GitHub: https://github.com/Cap-go/capacitor-passkey/
- ドキュメント: /docs/plugins/passkey/
@capgo/capacitor-passkey の使用方法から進む
使用している場合 @capgo/capacitor-passkey を使用する 認証とアカウントフローを計画するには、これを次と連携させてください @capgo/capacitor-passkey @capgo/capacitor-passkey の実装詳細については、 スタートガイド スタートガイドの実装詳細については、 @capgo/capacitor-social-login @capgo/capacitor-social-login の実装の詳細については、 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric の実装の詳細、および 2要素認証 二要素認証の実装の詳細については。