Menggunakan @capgo/capacitor-passkey

Tahan browser-style WebAuthn code di aplikasi Capacitor sementara plugin mengelola panggilan passkey native dan patching host native.

Browser-style API

@capgo/capacitor-passkey Browser-style __CAPGO_KEEP_0__ menjaga alur WebAuthn yang sama seperti yang Anda gunakan di web:

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

On native builds, the plugin installs a shim for navigator.credentials.create() dan navigator.credentials.get(), mengirimkan permintaan ke API passkey iOS dan Android, dan mengembalikan objek kreditur seperti browser ke aplikasi Anda.

Install dan sinkronkan proyek native

bun add @capgo/capacitor-passkey
bunx cap sync

Konfigurasi aplikasi host sekali saja

Tambahkan konfigurasi plugin di capacitor.config.ts atau 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;

Apa yang dilakukan konfigurasi plugin

Konfigurasi dibaca dari plugins.CapacitorPasskey dalam capacitor.config.*.

origin: asal HTTPS utama yang dipakai oleh shim dan API
domains: nama host tambahan yang dipakai untuk memperbaiki konfigurasi native selama sinkronisasi
autoShim: default ke true dan mengontrol native cap sync hook auto-konfigurasi

Jalankan sinkronisasi lagi setelah mengubah konfigurasi:

bunx cap sync

Instal shim selama bootstrap

Import plugin dari entri paket standar, kemudian instal shim selama bootstrap aplikasi:

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

await CapacitorPasskey.autoShimWebAuthn();

After that, your existing browser-style passkey code can stay the same.

Jika Anda perlu memaksa shim atau menggantikan asal yang dikonfigurasi pada waktu runtime, panggil:

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

CapacitorPasskey.shimWebAuthn({
  origin: 'https://signin.example.com',
});

Tetapkan aliran WebAuthn normal Anda

const credential = await navigator.credentials.create({
  publicKey: registrationOptions,
});

const assertion = await navigator.credentials.get({
  publicKey: requestOptions,
});

Apa yang memperbarui patch untuk Anda

Selama bunx cap sync, plugin memperbarui proyek host native yang dihasilkan:

iOS: hak akses domain terkait dan pengaturan Xcode ketika diperlukan
Android: asset_statements metadata dan sumber daya yang dihasilkan yang digunakan oleh manifest

Pengaturan native masih memerlukan file kepercayaan website

Plugin ini mengurangi pekerjaan di sisi aplikasi, tetapi passkeys masih bergantung pada file kepercayaan situs untuk domain pihak yang bergantung. Anda masih perlu menyimpan:

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

Plugin ini dapat memperbaiki proyek native yang dihasilkan selama sinkronisasi, tetapi tidak dapat membuat atau menyimpan file kepercayaan situs tersebut untuk Anda.

Metode publik lainnya

Plugin publik API juga mengekspos bantuan langsung yang ditentukan dalam src/definitions.ts:

await CapacitorPasskey.getConfiguration() mengembalikan nilai yang telah terpecahkan origin, domains, autoShim, dan saat ini platform.
await CapacitorPasskey.createCredential(...) mendaftarkan passkey dari payload WebAuthn yang aman JSON.
await CapacitorPasskey.getCredential(...) otentikasi dengan passkey yang sudah ada dari payload WebAuthn yang aman JSON.
await CapacitorPasskey.isSupported() melaporkan apakah runtime saat ini mendukung passkeys.
await CapacitorPasskey.getPluginVersion() mengembalikan tanda pembaruan implementasi native saat ini.

Petunjuk platform

Pesan Penting iOS

Pada iOS 17.4 dan lebih baru, plugin ini menggunakan klien-data browser-style API sehingga asal HTTPS yang dikonfigurasi tercermin dalam clientDataJSON.

Pesan Penting Android

Pengelola Kredensial Android dapat berbagi pihak yang dipercaya dan kunci pasword dengan situs web Anda ketika Digital Asset Links dikonfigurasi, tetapi asal asertasi native tidak identik dengan asal browser. Jika backend Anda secara ketat memvalidasi clientDataJSON.origin, pastikan Anda menerima asal aplikasi Android di samping asal situs web Anda.

Referensi Lengkap

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

Teruskan dari Menggunakan @capgo/capacitor-passkey

Jika Anda menggunakan Menggunakan @capgo/capacitor-passkey untuk merencanakan alur autentikasi dan akun, hubungkannya dengan @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, Getting Started untuk detail implementasi di Getting Started, @capgo/capacitor-social-login untuk detail implementasi di @capgo/capacitor-social-login, @capgo/capacitor-native-biometric untuk detail implementasi di @capgo/capacitor-native-biometric, dan Autentikasi dua faktor untuk detail implementasi di Autentikasi dua faktor.

Passkey

Tutorial tentang Passkey