Passkey Plugin Capacitor

Utilizzo di @capgo/capacitor-passkey

Mantieni la tua code WebAuthn stile browser in un'app Capacitor, mentre il plugin gestisce le chiamate passkey native e il patching dell'host nativo.

API stile browser

@capgo/capacitor-passkey mantiene lo stesso flusso WebAuthn che già usi sul web:

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

Nei Native Build, il plugin installa uno shim per navigator.credentials.create() e navigator.credentials.get(), inoltra la richiesta alle API passkey di iOS e Android e restituisce alla tua app oggetti credential simili a quelli del browser.

Installa e sincronizza i progetti nativi

bun add @capgo/capacitor-passkey
bunx cap sync

Configura l'app host una sola volta

Aggiungi la configurazione del plugin in capacitor.config.ts o 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;

Cosa fa la config del plugin

La configurazione viene letta da plugins.CapacitorPasskey nella capacitor.config.*.

• origin: l'origine HTTPS della relying-party primaria usata dallo shim e API diretto
• domains: hostnames extra della relying-party da applicare alla config nativa durante la sync
• autoShim: il default è true e controlla la parte nativa cap sync hook di auto-configurazione

Esegui di nuovo la sync dopo aver modificato la config:

bunx cap sync

Installa lo shim durante il bootstrap

Importa il plugin dall'entrypoint standard del pacchetto, poi installa lo shim durante l'app bootstrap:

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

await CapacitorPasskey.autoShimWebAuthn();

Dopo di ciò, il tuo code esistente in stile browser può rimanere invariato.

Se devi forzare lo shim o sovrascrivere l'origin configurata a runtime, chiama:

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

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

Mantieni il tuo normale flusso WebAuthn

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

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

Cosa corregge la sync per te

Durante bunx cap sync, il plugin aggiorna i progetti nativi generati:

• iOS: configurazione degli associated domains e degli entitlements in Xcode, se necessario
• Android: asset_statements metadati e la risorsa generata usata dal manifest

Il setup nativo richiede ancora i file di trust del sito

Il plugin riduce il lavoro lato app, ma le passkey dipendono comunque dai file di trust del sito per il tuo dominio relying-party. Devi comunque ospitare:

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

Il plugin può patchare i progetti nativi durante la sync, ma non può creare o ospitare i file di trust del sito per te.

Altri metodi pubblici

Il plugin pubblico API espone anche gli helper diretti definiti in src/definitions.ts:

• await CapacitorPasskey.getConfiguration() restituisce il origin, domains, autoShim, e l'attuale platform.
• await CapacitorPasskey.createCredential(...) registra una passkey da un payload WebAuthn JSON-safe.
• await CapacitorPasskey.getCredential(...) autentica con una passkey esistente da un payload WebAuthn JSON-safe.
• await CapacitorPasskey.isSupported() indica se il runtime attuale supporta le passkey.
• await CapacitorPasskey.getPluginVersion() restituisce il marker di versione dell'implementazione nativa corrente.

Guide per piattaforma

• Guida rapida
• Setup iOS
• Configurazione Android
• Note sul backend

Nota importante per iOS

Su iOS 17.4 e versioni successive, il plugin usa il client-data API in stile browser, così l'origin HTTPS configurato viene riflesso in clientDataJSON.

Avvertenza importante per Android

Android Credential Manager può condividere la stessa relying party e le stesse passkey del tuo sito quando i Digital Asset Links sono configurati, ma l'origin dell'assertion nativa non è identica a quella di un browser. Se il tuo backend valida rigorosamente clientDataJSON.origin, assicurati che accetti l'origin dell'app Android oltre a quello del tuo sito.

Riferimento completo

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

Continua da Usare @capgo/capacitor-passkey

Se stai usando Utilizzo di @capgo/capacitor-passkey per pianificare i flussi di autenticazione e account, collegandolo a @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey, Per iniziare per i dettagli di implementazione nella guida introduttiva, @capgo/capacitor-social-login per i dettagli di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-native-biometric per i dettagli di implementazione in @capgo/capacitor-native-biometric, e Autenticazione a due fattori per i dettagli sull'implementazione dell'autenticazione a due fattori.