Mit @capgo/capacitor-passkey verwenden

Halten Sie Ihren Browser-WebAuthn code in einer Capacitor-Anwendung, während das Plugin native Passkey-Anrufe und native Host-Patching handhabt.

Browser-WebAuthn API

@capgo/capacitor-passkey Browser-WebAuthn __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()und leitet die Anfrage an die iOS- und Android-Passkey-APIs weiter, und gibt browserartige Kreditobjekte 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 capacitor.config.*.

origin: primäre HTTPS-Vertrauenspartei-Quelle, die vom Shim und dem direkten API verwendet wird
domains: zusätzliche Vertrauenspartei-Hostname, die in die native Konfiguration während der Synchronisierung eingepflegt werden
autoShim: standardmäßig true und steuert die native cap sync Automatisierung der Konfiguration

Synchronisierung erneut ausführen, nachdem die Konfiguration geändert wurde:

bunx cap sync

Installieren Sie den Shim während des Bootstraps

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

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

await CapacitorPasskey.autoShimWebAuthn();

Danach kann Ihr bestehender Browser-Stil-Passwort code unverändert bleiben.

Wenn Sie den Shim zwingen oder die konfigurierte Ursprung bei Laufzeit überschreiben müssen, rufen Sie:

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

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

Halten Sie Ihren normalen WebAuthn-Flow aufrecht

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

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

Was synchronisiert für Sie

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

iOS: Domänenzugehörigkeiten und Xcode-Zugriffsrechte verbinden, wenn erforderlich
Android: asset_statements Metadaten und die generierte Ressource, die vom Manifest verwendet wird

Nativsetup benötigt immer noch Website-Vertrauensdateien

Der Plugin reduziert die App-Seitenaufgaben, aber Passkeys hängen immer noch von den Website-Vertrauensdateien für Ihren Relying-Party-Domain ab. 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 Nativprojekte während der Synchronisierung anpassen, aber es kann diese Website-Vertrauensdateien für Sie nicht erstellen oder hosten.

Andere öffentliche Methoden

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

await CapacitorPasskey.getConfiguration() wird die aufgelöste origin, domains, autoShim, und aktuelle 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() berichtet, ob die aktuelle Laufzeitumgebung Passkeys unterstützt.
await CapacitorPasskey.getPluginVersion() wird die aktuelle Nativimplementierungsversionmarker zurückgegeben.

Plattform-Anleitungen

Wichtiger Hinweis zum iOS

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

Wichtige Android-Hinweise

Der Android Credential Manager kann die gleiche Relying-Party und Passwörter als Ihre Website teilen, wenn Digital Asset Links konfiguriert sind, aber die native Anmelde-Origin ist nicht identisch mit einem Browser-Origin. Wenn Ihr Backend streng clientDataJSON.originStellen Sie sicher, dass Ihr Backend die Android-App-Origin neben Ihrer Website-Origin akzeptiert.

Vollständige Referenz

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

Passwort

Tutorial zu Passkey