Zum Hauptinhalt springen
Capgo-Logo
Zurück zu Plugins
@capgo/capacitor-Passkey
Tutorial
von github.com/Cap-go

Passkey

Keep browser-style WebAuthn code in Capacitor while native passkey calls and host patching are handled for you

Downloads/Woche

40

GitHub Sterne

1

Richtlinie

Tutorial zu Passkey

Mit @capgo/capacitor-passkey verwenden

Halten Sie Ihren Browser-WebAuthn code in einer Capacitor-App, während das Plugin native Passwortanrufe und native Host-Patching verarbeitet.

Browser-API

@capgo/capacitor-passkey Browser-__CAPGO_KEEP_0__ hält den gleichen WebAuthn-Flow bei, den Sie bereits im Web verwenden: 

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

Bei nativen Builds installiert das Plugin einen Shim für navigator.credentials.create() und navigator.credentials.get(), leitet die Anfrage an die iOS- und Android-Passwort-APIs weiter und gibt browserähnliche Anmeldeobjekte an Ihre App zurück.

Installieren und synchronisieren Sie native Projekte

bun add @capgo/capacitor-passkey
bunx cap sync

Konfigurieren Sie die Host-App einmal

Fügen Sie die Plugin-Konfiguration in capacitor.config.ts oder 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;

Was die Plugin-Konfiguration tut

Die Konfiguration wird aus plugins.CapacitorPasskey in: primäre HTTPS Relying-Party-Quelle, die vom Shim und direkt verwendet wird capacitor.config.*.

  • origin: primary HTTPS relying-party origin used by the shim and direct API
  • domains: standardmäßig
  • autoShimund steuert die native true Auto-Konfigurations-Hook cap sync Run sync wiederholen, nachdem die Konfiguration geändert wurde:

Installieren Sie den Shim während des Bootstraps

bunx cap sync

Importieren Sie das Plugin aus dem Standard-Paket-Eintrittspunkt und installieren Sie den Shim während des App-Bootstraps:

Nachdem Sie das gemacht haben, kann Ihr bestehender Browser-Style-Passkey __CAPGO_KEEP_0__ unverändert bleiben.

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

await CapacitorPasskey.autoShimWebAuthn();

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

Halten Sie Ihren normalen WebAuthn-Flow aufrecht

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

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

Keep your normal WebAuthn flow

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

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

Was synchronisiert Patches für Sie

Während bunx cap sync, das Plugin aktualisiert die generierten native Host-Projekte:

  • iOS: Zugehörigkeitsdomänenberechtigungen und Xcode-Berechtigungen-Verkabelung, wenn erforderlich
  • Android: asset_statements Metadaten und die generierten Ressourcen, die vom Manifest verwendet werden

Die native Einrichtung benötigt immer noch Website-Vertrauensdateien

Das Plugin reduziert die Arbeit auf der App-Seite, aber Passwörter noch immer auf die Website-Vertrauensdateien für Ihr Relying-Party-Domain abhängig. Sie benötigen immer noch, um zu hosten:

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

Das Plugin kann die generierten native Projekte während der Synchronisierung patchen, aber es kann keine oder die Website-Vertrauensdateien für Sie erstellen oder hosten.

Andere öffentliche Methoden

Die öffentliche Plugin API offenbart auch die direkten Hilfsmittel, die in src/definitions.ts:

  • await CapacitorPasskey.getConfiguration() gibt die aufgelöste Rückgabe origin, domains, autoShim, und aktuell platform.
  • await CapacitorPasskey.createCredential(...) registriert eine Passkey aus einem JSON-sicheren WebAuthn-Payload.
  • await CapacitorPasskey.getCredential(...) authentifiziert sich mit einer bestehenden Passkey aus einem JSON-sicheren WebAuthn-Payload.
  • await CapacitorPasskey.isSupported() zeigt an, ob die aktuelle Laufzeit Passkeys unterstützt.
  • await CapacitorPasskey.getPluginVersion() gibt die aktuelle native Implementierungsversionssymbol zurück.

Plattform-Anleitungen

Wichtiger iOS-Hinweis

Bei iOS 17.4 und neuer verwendet der Plugin den browser-stiligen Client-Daten API so dass die konfigurierte HTTPS-Origin im API sichtbar ist. clientDataJSON.

Wichtiger Android-Hinweis

Der Android Credential Manager kann die gleiche Relying-Party und Passwörter wie Ihre Website teilen, wenn Digital Asset Links konfiguriert sind, aber die native Behauptung-Origin ist nicht identisch mit einem Browser-Origin. Wenn Ihr Backend streng die Validierung clientDataJSON.originvollzieht, stellen Sie sicher, dass es auch das Android-App-Origin neben Ihrem Website-Origin akzeptiert.

Vollständige Referenz