Saltare al contenuto principale
Logo Capgo
Torna ai plugin
@capgo/capacitor-passkey
Tutorial
di github.com/Cap-go

Passkey

Mantieni lo stile di browser WebAuthn code in Capacitor mentre le chiamate di passkey native e la patching del host sono gestiti per te

Download/settimana

40

GitHub Stelle

1

Guida

Tutorial su Passkey

Utilizzo di @capgo/capacitor-passkey

Mantieni il tuo WebAuthn code come se fosse un browser in un'app Capacitor mentre il plugin gestisce le chiamate di passkey native e il patching del host nativo.

Stile browser di API

@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 });

Nelle costruzioni native, il plugin installa un shim per navigator.credentials.create() e navigator.credentials.get(), invia la richiesta alle API passkey di iOS e Android, e restituisce oggetti di credenziali come se fossero del browser alla tua 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;

Cosa fa la configurazione del plugin

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

  • origin: origin HTTPS di riferimento primario utilizzato dal shim e diretto API
  • domains: hostnames di riferimento aggiuntivi da integrare nella configurazione nativa durante la sincronizzazione
  • autoShim: predefinito a true e controlla la configurazione nativa cap sync hook di configurazione auto

Esegui nuovamente la sincronizzazione dopo aver modificato la configurazione:

bunx cap sync

Installa il shim durante l'avvio

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

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'originato configurato 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,
});

Quali patch di sincronizzazione per te

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

  • iOS: autorizzazioni ai domini associati e configurazione delle autorizzazioni Xcode quando necessario
  • Android: asset_statements metadati e il file di risorsa generato utilizzato dal manifesto

La configurazione nativa richiede ancora i file di fiducia del sito web

Il plugin riduce il lavoro sul lato dell'app, ma le chiavi passate ancora dipendono dai file di fiducia del sito web per il tuo dominio di partito di fiducia. Hai ancora bisogno di ospitare:

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

Il plugin può patchare i progetti host nativi generati durante la sincronizzazione, ma non può creare o ospitare quei file di fiducia 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, autoShime attualmente platform.
  • await CapacitorPasskey.createCredential(...) si registra una chiave di accesso da un payload WebAuthn sicuro da JSON.
  • await CapacitorPasskey.getCredential(...) si autentica con una chiave di accesso esistente da un payload WebAuthn sicuro da JSON.
  • await CapacitorPasskey.isSupported() indica se il runtime corrente supporta le chiavi di accesso.
  • await CapacitorPasskey.getPluginVersion() restituisce il marker di versione dell'implementazione nativa corrente.

Guida alla piattaforma

Nota importante 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.

Nota importante per Android

Il Manager delle credenziali Android può condividere lo stesso partito di fiducia e le chiavi passkey del tuo sito web quando sono configurati i collegamenti di asset digitali, ma l'origine di attestazione 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