Mit @capgo/capacitor-passkey

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

Browser-WebAuthn API

@capgo/capacitor-passkey Browser-WebAuthn __CAPGO_KEEP_0__ hält den gleichen WebAuthn-Flow bei sich, 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()führt die Anfrage an die iOS- und Android-Passkey-APIs weiter und liefert 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 Wählen Sie 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 auf capacitor.config.*.

origin: primäre HTTPS-Vertrauenswürdige-Quelle, die vom Shim und dem direkten API verwendet wird
domains: zusätzliche Vertrauenswürdige-Hostnamen, die in die native Konfiguration während des Synchronisierungsprozesses eingepflegt werden
autoShim: standardmäßig true und steuert die native cap sync Automatisierung des Konfigurationshakens

Laufen Sie den Synchronisierungsprozess erneut, nachdem Sie die Konfiguration geändert haben:

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-Passkey code unverändert bleiben.

Wenn Sie die Shim zwingen oder die konfigurierte Ursprungsadresse 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-Fluss aufrecht.

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

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

Was synchronisiert Etwas für Sie.

Während bunx cap syncder Plugin aktualisiert die generierten native Host-Projekte:

iOS: Zugehörigkeitsberechtigungen und Xcode-Berechtigungen-Verkabelung, 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 Passkeys 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 nicht erstellen oder diese Website-Vertrauensdateien für Sie erstellen.

Weitere öffentliche Methoden

Der öffentliche Plugin API gibt auch die direkten Hilfsmittel an, die in src/definitions.ts:

await CapacitorPasskey.getConfiguration() gibt die aufgelöste origin, domains, autoShim, und aktuelle platform.
await CapacitorPasskey.createCredential(...) registriert einen Passkey aus einem JSON-sicheren WebAuthn-Payload.
await CapacitorPasskey.getCredential(...) authentifiziert sich mit einem 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 , sodass der konfigurierte HTTPS- Ursprung im 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 des Ursprungs ist nicht identisch mit einem Browser-Ursprung. Wenn Ihr Backend streng die Validierung clientDataJSON.originstellt sicher, dass es die Android-App-Ursprüngseit akzeptiert, neben Ihrer Website-Ursprüngseit.

Vollständige Referenz

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

Fortsetzen Sie mit der Verwendung von @capgo/capacitor-passkey

Wenn Sie die Verwendung von Mit @capgo/capacitor-passkey um die Authentifizierung und die Kontoflussplanung vorzubereiten und 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.