Passkey plugin Capacitor

Utilizza @capgo/capacitor-passkey

Mantieni il tuo browser-style WebAuthn code in un'applicazione Capacitor mentre il plugin gestisce le chiamate native di passkey e il patching del host nativo.

Browser-style API

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

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

On native builds, il plugin installa un shim per navigator.credentials.create() e navigator.credentials.get()e invia la richiesta alle API di passkey iOS e Android, e restituisce oggetti di credenziali browser-like al tuo app.

Installa e sincronizza progetti nativi

bun add @capgo/capacitor-passkey
bunx cap sync

Configura l'app host una 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;

Come funziona la configurazione del plugin?

Come viene letta la configurazione del plugin? plugins.CapacitorPasskey In capacitor.config.*.

• origin: origine HTTPS primaria utilizzata dal shim e diretto API
• domains: host aggiuntivi per il patching della configurazione nativa durante la sincronizzazione
• autoShim: predefinito true e controlla la configurazione nativa cap sync hook di configurazione automatica

Run sync again after changing the config:

bunx cap sync

Installare il shim durante l'avvio

Importa il plugin dall'ingresso standard del pacchetto, quindi installa il shim durante l'avvio dell'app:

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

await CapacitorPasskey.autoShimWebAuthn();

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

Se hai bisogno di forzare il shim o sovrascrivere l'origine configurata in esecuzione, chiama:

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

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

Mantieni il tuo flusso WebAuthn normale

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

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

Cosa le patch di sincronizzazione fanno per te

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

• iOS: autorizzazioni di dominio associati e autorizzazioni Xcode quando necessario
• Android: asset_statements metadati e il risorsa generata utilizzata dal manifesto

Configurazione nativa richiede ancora file di trust del sito web

Il plugin riduce il lavoro sul lato dell'app, ma le passkey dipendono ancora dai file di fiducia del sito web per il tuo dominio di parte di riferimento. Ancora devi ospitare:

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

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

Altri metodi pubblici

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

• await CapacitorPasskey.getConfiguration() ritorna la risoluzione origin, domains, autoShim, e corrente platform.
• await CapacitorPasskey.createCredential(...) registra una chiave pass da un payload WebAuthn sicuro JSON.
• await CapacitorPasskey.getCredential(...) autentica con una chiave pass esistente da un payload WebAuthn sicuro JSON.
• await CapacitorPasskey.isSupported() riferisce se il runtime corrente supporta le chiavi pass.
• await CapacitorPasskey.getPluginVersion() ritorna la versione di marcatura dell'implementazione nativa corrente.

Guida per le piattaforme

• Getting started
• Impostazione iOS
• Impostazione Android
• Note sul backend

Nota importante per iOS

Sul iOS 17.4 e versioni successive, il plugin utilizza il client-data di tipo browser API quindi l'origine HTTPS configurata viene riflessa in clientDataJSON.

Avvertimento importante per Android

Manager delle credenziali Android può condividere lo stesso partito di fiducia e le chiavi pass per il tuo sito web quando sono configurati i collegamenti di asset digitali, ma l'origine di affermazione nativa non è identica a un'origine del browser. Se il tuo backend verifica rigorosamente clientDataJSON.originAssicurati che accetti l'origine dell'app Android accanto all'origine del tuo sito web.

Riferimento completo

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

Continua dall'uso di @capgo/capacitor-passkey

Se stai utilizzando Utilizza @capgo/capacitor-passkey per pianificare l'autenticazione e i flussi di account, connettilo con @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey Getting Started per i dettagli di implementazione in Getting Started @capgo/capacitor-login con social media per i dettagli di implementazione in @capgo/capacitor-social-login @capgo/capacitor-nativo-biometrico per i dettagli di implementazione in @capgo/capacitor-native-biometric, e Autenticazione a due fattori per i dettagli di implementazione in Autenticazione a due fattori.