Passkey Capacitor-Plugin

Verwendung von @capgo/capacitor-passkey

Halten Sie Ihren browser-stiligen WebAuthn code in einer Capacitor-App, während das Plugin native Passwortanrufe und native Host-Patching verarbeitet.

Browser-stil API

@capgo/capacitor-passkey Bleibt bei der gleichen WebAuthn-Fluss, den Sie bereits im Web verwenden:

await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });

On native Builds installiert das Plugin einen Shim für navigator.credentials.create() und navigator.credentials.get(), die Anfrage an die iOS- und Android-Passkey-APIs weiterleitet und browserartige Anmeldeobjekte an Ihre App zurückgibt.

Installieren und synchronisieren Sie native Projekte

bun add @capgo/capacitor-passkey
bunx cap sync

Konfigurieren Sie das Host-App einmal

Hinzufü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: die primäre HTTPS-Vertrauensstelle, die vom Shim und direkt verwendet wird API
• domains: extra relying-party hostnames to patch into native config during sync
• autoShimdefaults zu true und kontrolliert die native cap sync auto-Konfigurations-Hook

Run sync again after changing the config:

bunx cap sync

Installieren Sie den Shim während des Bootstraps

Importieren Sie das Plugin aus dem Standard-Paket-Einstiegspunkt, installieren Sie dann den Shim während des Anwendungs-Bootstraps:

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

await CapacitorPasskey.autoShimWebAuthn();

Danach kann Ihr bestehender Browser-Style-Passkey 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',
});

Behalten Sie Ihren normalen WebAuthn-Flow bei

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: Berechtigungen für assoziierte Domains und Xcode-Berechtigungen werden wie erforderlich konfiguriert.
• Android: asset_statements Metadaten und die generierte Ressource, die vom Manifest verwendet wird.

Eigene Einrichtung benötigt noch Website-Vertrauensdateien

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

Sonstige öffentliche Methoden

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

• await CapacitorPasskey.getConfiguration() Die Methode gibt die aufgelöste origin, domains, autoShimund derzeit 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() erklärt, ob die aktuelle Laufzeitumgebung Passkeys unterstützt.
• await CapacitorPasskey.getPluginVersion() gibt die aktuelle native Implementierungsversion zurück.

Plattformleitfäden

• Anleitung zum Starten
• iOS-Einrichtung
• Android-Einrichtung
• Hinweise zum Backend

Wichtiger Hinweis zum iOS

Bei iOS 17.4 und neuer verwendet der Plugin die browserartige Client-Daten API , sodass die konfigurierte HTTPS-Origin in clientDataJSON.

Wichtiger Android-Hinweis

Der Android-Credential-Manager kann die gleiche Relying-Party und Passkeys wie Ihre Website teilen, wenn Digital Asset Links konfiguriert sind, aber die native Anmeldeursprung ist nicht identisch mit einem Browser- Ursprung. Wenn Ihr Backend streng die Validierung 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/

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

Wenn Sie die Verwendung von Die Verwendung von @capgo/capacitor-passkey um die Authentifizierung und die Kontoflows zu planen, verbinden Sie es mit @capgo/capacitor-passkey zur Implementierungsdetail in @capgo/capacitor-passkey Anleitung zum Starten zur Implementierungsdetail in Anleitung zum Starten @capgo/capacitor-Social-Login für die Implementierungsdetails in @capgo/capacitor-social-login @capgo/capacitor-native-biometrisch für die Implementierungsdetails in @capgo/capacitor-native-biometric und Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung.