Mit @capgo/capacitor-passkey

Behalte deine Browser-ähnliche WebAuthn code in einer Capacitor-App, während das Plugin native Passkey-Aufrufe und native Host-Patching verwaltet.

Browser-ähnliche API

@capgo/capacitor-passkey Behalte die gleiche WebAuthn-Fluss, den du bereits im Web verwendest:

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-artige Anmeldeobjekte an deine App zurück.

Installiere und synchronisiere native Projekte

bun add @capgo/capacitor-passkey
bunx cap sync

Konfiguriere die Host-App einmal

Füge 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: Haupt-HTTPS-Vertrauenspartei-Quelle, die vom Shim und dem direkten API verwendet wird
domains: Zusätzliche Vertrauenspartei-Hostnamen, die in die native Konfiguration während der Synchronisierung eingepflegt werden
autoShim: Standardmäßig true und steuert die native cap sync Automatisierung der Konfiguration

Laufen Sie die Synchronisierung noch einmal nach dem Ändern der Konfiguration aus

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 die konfigurierte Ursprungsadresse 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-Fluss bei

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

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

Was synchronisiert Patches für Sie

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

iOS: Zugehörigkeitsberechtigungen für Domänen und Xcode-Zugriffsrechte, 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

Der öffentliche Plugin API stellt auch die direkten Hilfsmittel dar, 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() berichtet, ob die aktuelle Laufzeitumgebung Passkeys unterstützt.
await CapacitorPasskey.getPluginVersion() gibt die aktuelle native Implementierungsversionssymbolik zurück.

Plattform-Anleitungen

Wichtiger iOS-Hinweis

Bei iOS 17.4 und neuer verwendet das Plugin den browser-stiligen Client-Daten API , sodass die konfigurierte HTTPS-Origin 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-Origin ist nicht identisch mit einem Browser-Origin. Wenn Ihr Backend streng die Validierung 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/

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

Wenn Sie die Mit @capgo/capacitor-passkey um Authentifizierungs- und Kontoflusspläne zu planen und es mit @capgo/capacitor-passkey zur Implementierungsdetail in @capgo/capacitor-passkey, Anfänger zur Implementierungsdetail in Anfänger, @capgo/capacitor-social-login zur Implementierungsdetail in @capgo/capacitor-social-login, @capgo/capacitor-native-biometric zur Implementierungsdetail in @capgo/capacitor-native-biometric und Zwei-Faktor-Authentifizierung zur Implementierungsdetail in Zwei-Faktor-Authentifizierung.

Passkey

Tutorial zu Passkey