Verwenden Sie @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 auf der Webseite 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()Die Anfrage wird an die iOS- und Android-Passwort-APIs weitergeleitet und browserartige Anmeldeinformationen als Objekte an Ihre App zurückgegeben.

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 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 macht die Plugin-Konfiguration?

Die Konfiguration wird aus plugins.CapacitorPasskey in capacitor.config.*.

origin: Haupt-HTTPS-Vertrauenspartner-Quelle, die vom Shim verwendet und direkt API
domains: Zusätzliche Vertrauenspartner-Hostnamen, die in die native Konfiguration während der Synchronisierung eingepflegt werden
autoShim: Standardmäßig true und steuert die native cap sync Automatisierungs-Hook

Run sync wieder nach dem Ändern der Konfiguration:

bunx cap sync

Installieren Sie den Shim während des Bootstraps

Importieren Sie das Plugin aus dem Standard-Paket-Eintrittspunkt, installieren Sie dann den Shim während des Anwendungs-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 den Shim zwingen oder den konfigurierten 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 Sie für Sie

Während bunx cap sync, aktualisiert das Plugin die generierten native Host-Projekte:

iOS: Zugehörigkeitsdomänen-Beistellungen und Xcode-Beistellungen-Verkabelung, wenn erforderlich
Android: asset_statements Metadaten und die generierte Ressource, die vom Manifest verwendet wird

Die native Einrichtung benötigt immer noch die Vertrauensdateien der Website

Das Plugin reduziert die Arbeit auf der App-Seite, aber Passkeys hängen immer noch von den Vertrauensdateien der Website für Ihren 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 des Synchronisierens patchen, aber es kann diese Vertrauensdateien für Sie nicht erstellen oder hosten.

Andere öffentliche Methoden

Das öffentliche Plugin API enthält 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 eine Passkey aus einem JSON-sicheren WebAuthn-Payload.
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() wird die aktuelle native Implementierungsversionmarker zurückgegeben.

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 im clientDataJSON.

Wichtige Android-Hinweise

Android Credential Manager kann die gleiche Relying-Party und Passwörter als Ihre Website teilen, wenn Digital Asset Links konfiguriert sind, aber die native Anmelde-Origin ist nicht identisch mit einem Browser-Origin. Wenn Ihr Backend streng 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/

Weitermachen von Using @capgo/capacitor-passkey

Wenn Sie Using verwenden 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-biometrische für die Implementierungsdetails in @capgo/capacitor-native-biometrische, und Zweifaktor-Authentifizierung für die Implementierungsdetails in Zweifaktor-Authentifizierung.

Passkey

Tutorial zu Passkey