Passkey Plugin Capacitor

Menggunakan @capgo/capacitor-passkey

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

Authn browser-style API

@capgo/capacitor-passkey tetapkan alur WebAuthn yang sama seperti yang kamu gunakan di web:

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

On build asli, plugin menginstal shim untuk navigator.credentials.create() dan navigator.credentials.get(), mengirim permintaan ke API passkey iOS dan Android, dan mengembalikan objek kreditur seperti browser ke aplikasi Anda.

Install dan sinkronisasi proyek asli

bun add @capgo/capacitor-passkey
bunx cap sync

Konfigurasi aplikasi host sekali

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 digunakan oleh shim dan API
• domains: hostname tambahan yang dipatch ke konfigurasi asli selama sinkronisasi
• autoShim: defaults ke true dan mengontrol native cap sync hook konfigurasi otomatis

Jalankan sync lagi setelah mengubah konfigurasi:

bunx cap sync

Pasang shim selama bootstrap

Import plugin dari entrypoint paket standar, kemudian pasang shim selama bootstrap aplikasi:

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

await CapacitorPasskey.autoShimWebAuthn();

Setelah itu, passkey browser-style code yang sudah ada Anda bisa biarkan tetap sama.

Jika Anda perlu memaksa shim atau mengganti 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 saja patch sync untuk Anda

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

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

Pengaturan asli masih memerlukan file kepercayaan situs

Plugin ini mengurangi pekerjaan di sisi aplikasi, tetapi passkeys masih bergantung pada file kepercayaan situs untuk domain pihak yang dipercaya Anda. 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-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() kembali ke 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() mengetahui apakah runtime saat ini mendukung passkeys.
• await CapacitorPasskey.getPluginVersion() mengembalikan versi marker implementasi native saat ini.

Petunjuk Platform

• Mulai Menggunakan
• Pengaturan iOS
• Pengaturan Android
• Catatan Backend

Peringatan Penting iOS

Pada iOS 17.4 dan lebih baru, plugin 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 passkeys 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 autentikasi dan alur akun, hubungkannya dengan @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey Mulai Menggunakan untuk detail implementasi di Berikut, di @capgo/capacitor-login-sosial untuk detail implementasi di @capgo/capacitor-login-sosial, di @capgo/capacitor-biometrik-nativ untuk detail implementasi di @capgo/capacitor-biometrik-nativ, dan Autentikasi dua faktor untuk detail implementasi di Autentikasi dua faktor.