Saltare al contenuto principale
Capgo logo
Indietro ai plugin
@capgo/capacitor-passkey
Tutorial
da github.com/Cap-go

Passkey

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

Download/settimana

3.0k

GitHub Stelle

2

Guida

Tutorial su Passkey

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à utilizzate 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()inoltra la richiesta alle API di passkey di iOS e Android, e restituisce oggetti di credenziali simili a quelli del browser per la tua app.

Installare e sincronizzare progetti nativi

bun add @capgo/capacitor-passkey
bunx cap sync

Configura l'app host una volta sola

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: origine HTTPS primaria del provider di fiducia utilizzata dal shim e diretto API
  • domains: hostnames aggiuntivi del provider di fiducia da integrare nella configurazione nativa durante la sincronizzazione
  • autoShim: predefinito a true e controlla la configurazione auto del hook nativo cap sync regola l'hook di configurazione auto del nativo

Esegui sincronizzazione nuovamente 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();

Dopo di che, il tuo passkey esistente per browser può rimanere lo stesso code.

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 sincronizza per te

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

  • iOS: autorizzazioni dei domini associati e autorizzazioni Xcode quando necessario
  • Android: asset_statements metadati e le risorse generate utilizzate 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 pass sono ancora dipendenti 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 nativi generati durante la sincronizzazione, ma non può creare o ospitare questi file di fiducia del sito web per te.

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 alle piattaforme

Nota importante per iOS

In 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.

Cautela importante per Android

Il Manager delle credenziali Android può condividere lo stesso partito affidabile e le chiavi passkey del 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