Mit @capgo/capacitor-passkey

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

Browser-ähnlicher API

@capgo/capacitor-passkey beibehält den gleichen WebAuthn-Flow, den Sie bereits auf der Webseite 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-Passkey-APIs weiter und liefert browserähnliche Kredenzialobjekte an Ihre App.

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 hinzu 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ärer HTTPS-Vertrauenspartner-Quellort, der vom Shim und direkt verwendet wird API
domains: Zusätzliche Vertrauenspartner-Hostnamen, die in die native Konfiguration während der Synchronisierung eingepflegt werden
autoShim: Standardmäßig true und steuert die native cap sync Automatische Konfigurations-Hook

Synchronisierung noch einmal 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 App-Bootstraps:

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

await CapacitorPasskey.autoShimWebAuthn();

Nachdem Sie das gemacht haben, kann Ihr bestehender Browser-Stil-Passwort code unverändert bleiben.

Wenn Sie die Shim zwingen oder den konfigurierten 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 synchronisierte Patches für Sie machen

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

iOS: Zugehörigkeitsberechtigungen für Domains und Xcode-Berechtigungen, wenn erforderlich
Android: asset_statements Metadaten und die generierte Ressource, die vom Manifest verwendet wird

Die native Einrichtung benötigt immer noch Website-Vertrauensdateien

Das Plugin reduziert die Arbeit auf der App-Seite, aber Passwörter hängen immer noch von den Website-Vertrauensdateien für Ihr 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 native Projekte während der Synchronisierung patchen, aber es kann keine oder die Website-Vertrauensdateien für Sie erstellen oder hosten.

Weitere öffentliche Methoden

Das öffentliche Plugin API enthält auch die direkten Hilfsfunktionen, die in src/definitions.ts:

await CapacitorPasskey.getConfiguration() gibt 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() zeigt an, ob die aktuelle Laufzeit Passkeys unterstützt.
await CapacitorPasskey.getPluginVersion() gibt die aktuelle native Implementierungsversion Marker zurück.

Plattform-Anleitungen

Wichtiger iOS-Hinweis

Bei iOS 17.4 und neuer verwendet das Plugin den browser-stiligen Client-Daten API so dass die konfigurierte HTTPS-Origin in 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 Anmeldeursprung ist nicht identisch mit einem Browserursprung. Wenn Ihr Backend streng clientDataJSON.originstellt sicher, dass es die Android-App-Ursprung neben Ihrer Website-Ursprung akzeptiert.

Vollständige Referenz

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

Weitermachen von Using @capgo/capacitor-passkey

Wenn Sie Using verwenden Mit @capgo/capacitor-passkey für die Planung der Authentifizierung und der Kontoflows, verbinden Sie es mit @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey, Einstieg für die Implementierungsdetails in Einstieg, @capgo/capacitor-social-login für die Implementierungsdetails in @capgo/capacitor-social-login, @capgo/capacitor-native-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, und Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung.

Passkey

Tutorial zu Passkey