Mit @capgo/capacitor-passkey verwenden

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

Browser-WebAuthn API

@capgo/capacitor-passkey Bleibt bei dem gleichen WebAuthn-Fluss, den Sie bereits auf der Webanwendung 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 Kredenzialobjekte an Ihre Anwendung zurück.

Installieren und native Projekte 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-Quelle, 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 auf 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,
});

Welche Synchronisierungs-Patches werden für Sie durchgeführt

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 Anwendungsseite-Arbeit, aber Passwörter basieren jedoch auf den Vertrauensdateien Ihres Relying-Party-Domains für die Website. Sie müssen immer noch 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 anpassen, kann diese jedoch nicht erstellen oder hosten.

Andere öffentliche Methoden

Der ö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 ein Passwort aus einem JSON-sicheren WebAuthn-Payload.
await CapacitorPasskey.getCredential(...) authentifiziert sich mit einem bestehenden Passwort aus einem JSON-sicheren WebAuthn-Payload.
await CapacitorPasskey.isSupported() berichtet, ob die aktuelle Laufzeitumgebung Passwörter unterstützt.
await CapacitorPasskey.getPluginVersion() wird die aktuelle native Implementierungsversionssymbol.

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 in API clientDataJSON.

Wichtiger Android-Hinweis

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 Behauptung-Origin ist nicht identisch mit einem Browser-Origin. Wenn Ihr Backend streng validiert clientDataJSON.originStellen Sie 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 Mit der Verwendung von @capgo/capacitor-passkey um die Authentifizierung und die Kontenflüsse zu planen und zu verbinden, 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 Zweifaktor-Authentifizierung für die Implementierungsdetails in der Zweifaktor-Authentifizierung.

Passkey

Tutorial zum Passwort