Passkey plugin Capacitor

Menggunakan @capgo/capacitor-passkey

Gunakan code WebAuthn ala browser di aplikasi Capacitor sementara plugin menangani pemanggilan passkey native dan native host patching.

API ala browser

@capgo/capacitor-passkey tetap menggunakan alur WebAuthn yang sama dengan di web:

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

Pada Native Build, plugin ini memasang shim untuk navigator.credentials.create() dan navigator.credentials.get(), meneruskan request ke API passkey iOS dan Android, serta mengembalikan objek kredensial mirip browser ke aplikasi Anda.

Install dan sinkronisasi proyek native

bun add @capgo/capacitor-passkey
bunx cap sync

Konfigurasi host app satu kali

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;

Fungsi konfigurasi plugin

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

• origin: origin relying-party HTTPS utama yang digunakan oleh shim dan API langsung
• domains: hostname relying-party tambahan untuk di-patch ke config native saat sync
• autoShim: defaultnya adalah true dan mengontrol native cap sync hook auto-konfigurasi

Jalankan sync lagi setelah mengubah config:

bunx cap sync

Install shim saat bootstrap

Import plugin dari entrypoint package standar, lalu install shim saat bootstrap aplikasi:

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

await CapacitorPasskey.autoShimWebAuthn();

Setelah itu, passkey code bergaya browser Anda yang sudah ada bisa tetap sama.

Jika Anda perlu memaksa shim atau menimpa origin yang sudah dikonfigurasi saat runtime, panggil:

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

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

Tetap gunakan alur WebAuthn normal Anda

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

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

Apa yang di-patch sync untuk Anda

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

• iOS: entitlements associated domains dan wiring Xcode entitlements jika diperlukan
• Android: asset_statements metadata dan resource yang dihasilkan untuk digunakan oleh manifest

Setup Native tetap membutuhkan website trust files

Plugin ini mengurangi beban kerja di sisi app, namun passkey tetap bergantung pada website trust files untuk domain relying-party Anda. Anda tetap perlu menghosting:

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

Plugin dapat melakukan patch pada proyek native saat sync, tetapi tidak bisa membuat atau menghosting website trust files tersebut untuk Anda.

Metode publik lainnya

Plugin publik API juga menyediakan helper langsung yang didefinisikan di src/definitions.ts:

• await CapacitorPasskey.getConfiguration() mengembalikan hasil resolusi origin, domains, autoShim, dan saat ini platform.
• await CapacitorPasskey.createCredential(...) mendaftarkan passkey dari payload WebAuthn yang JSON-safe.
• await CapacitorPasskey.getCredential(...) melakukan autentikasi dengan passkey yang ada dari payload WebAuthn yang aman untuk JSON.
• await CapacitorPasskey.isSupported() melaporkan apakah runtime saat ini mendukung passkeys.
• await CapacitorPasskey.getPluginVersion() mengembalikan penanda versi implementasi native saat ini.

Panduan Platform

• Memulai penggunaan
• Setup iOS
• Setup Android
• Catatan backend

Catatan penting iOS

Pada iOS 17.4 ke atas, plugin menggunakan client-data API gaya browser sehingga origin HTTPS yang dikonfigurasi tercermin dalam clientDataJSON.

Catatan penting Android

Android Credential Manager dapat berbagi relying party dan passkeys yang sama dengan website Anda jika Digital Asset Links dikonfigurasi, namun origin assertion native tidak identik dengan origin browser. Jika backend Anda memvalidasi secara ketat clientDataJSON.origin, pastikan ia menerima origin aplikasi Android bersamaan dengan origin website Anda.

Referensi Lengkap

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

Lanjutkan dari Menggunakan @capgo/capacitor-passkey

Jika Anda menggunakan Menggunakan @capgo/capacitor-passkey untuk merencanakan alur autentikasi dan akun, hubungkan dengan @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, Panduan Memulai 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.