Lompat ke konten utama
Capgo logo
Kembali ke plugin
@capgo/capacitor-passkey
Tutorial
oleh github.com/Cap-go

Passkey

Tetapkan WebAuthn gaya browser code di Capacitor sementara panggilan passkey asli dan patching host diatur untuk Anda

Unduh/minggu

4.8k

GitHub Bintang

2

Petunjuk

Tutorial Menggunakan Passkey

Menggunakan @capgo/capacitor-passkey

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

Browser-style API

@capgo/capacitor-passkey Menggunakan alur WebAuthn yang sama seperti yang Anda gunakan di web:

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

Pada bangun native, plugin menginstal shim untuk navigator.credentials.create() dan navigator.credentials.get(), mengirimkan permintaan ke API passkey iOS dan Android, dan mengembalikan objek kreditur seperti browser ke aplikasi Anda.

Instal 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 langsung
  • domains: nama-nama asal tambahan untuk memperbaiki ke dalam konfigurasi native selama sinkron
  • autoShim: default ke true dan mengontrol native cap sync hook pengaturan otomatis

Jalankan sync lagi setelah mengubah konfigurasi:

bunx cap sync

Pasang shim selama proses bootstrapping

Impor plugin dari entrypoint paket standar, kemudian pasang shim selama proses bootstrapping 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 runtime, panggil:

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

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

Tetapkan alur WebAuthn normal Anda

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

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

Apa saja patch sync 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 asli masih memerlukan file kepercayaan website

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

  • 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 menghosting file-file kepercayaan website tersebut untuk Anda.

Metode publik lainnya

Plugin publik API juga mengungkapkan helper 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 verifikasi native saat ini.

Petunjuk platform

Peringatan Penting iOS

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

Peringatan Penting Android

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

Referensi Lengkap