Mit @capgo/capacitor-passkey verwenden

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

Browser-API

@capgo/capacitor-passkey beibehält den gleichen WebAuthn-Fluss, 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-Passkey-APIs weiter und gibt browserähnliche Kredenzialobjekte an Ihre App zurück.

Native-Projekte installieren und synchronisieren

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-Vertrauenspartner-URL, die vom Shim verwendet und direkt API
domains: zusätzliche Vertrauenspartner-Hostnamen zum Patchen in die native Konfiguration während der Synchronisierung
autoShim: standardmäßig true und steuert die native cap sync Automatisierung des Konfigurations-Hooks

Synchronisieren Sie erneut nach der Änderung der Konfiguration:

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();

Nachdem Sie das getan haben, 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 bei

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

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

Welche Synchronisierungspatches für Sie

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

The Plugin reduziert die Anwendungsseite-Arbeit, aber Passkeys hängen immer noch von den Vertrauensdateien der Website für Ihr Relying-Party-Domain ab. Sie benötigen immer noch:

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

Das Plugin kann die generierten nativen Projekte während der Synchronisierung anpassen, aber es kann weder die Erstellung noch die Bereitstellung dieser Vertrauensdateien für Sie erstellen.

Öffentliche Methoden

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

await CapacitorPasskey.getConfiguration() den aufgelösten origin, domains, autoShimund aktuellen platform.
await CapacitorPasskey.createCredential(...) eine Passkey aus einem JSON-sicheren WebAuthn-Payload registriert.
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() den aktuellen nativen Implementierungsversionsschlagwort zurückgibt.

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

Android Credential Manager kann die gleiche Relying-Party und Passwörter als 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 clientDataJSON.originstellt sicher, dass es die Android-App-Origin neben Ihrer Website-Origin akzeptiert.

Vollständige Referenz

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

Bleiben Sie bei der Verwendung von @capgo/capacitor-passkey

Wenn Sie Using verwenden Mit der Verwendung von @capgo/capacitor-passkey um die Authentifizierung und die Kontoflows zu planen, 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 Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung.

Passwort

Tutorial zu Passkey