Passkey Capacitor Plugin

@capgo/capacitor-passkey verwenden

Nutze dein browserbasiertes WebAuthn code in einer Capacitor App, während das Plugin die nativen Passkey-Aufrufe und das native Host-Patching übernimmt.

Browserbasiertes API

@capgo/capacitor-passkey behält den WebAuthn-Flow bei, den du bereits im Web nutzt:

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

Bei Native Builds installiert das Plugin einen Shim für navigator.credentials.create() und navigator.credentials.get(), leitet die Anfrage an die Passkey-APIs von iOS und Android weiter und gibt browserähnliche Credential-Objekte an deine App zurück.

Native Projekte installieren und synchronisieren

bun add @capgo/capacitor-passkey
bunx cap sync

Host-App einmalig konfigurieren

Plugin-Konfiguration hinzufügen 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 bewirkt

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

• origin: primärer HTTPS-Relying-Party-Origin, der vom Shim und von direktem API genutzt wird
• domains: zusätzliche Relying-Party-Hostnames, die während des Syncs in die native Config gepatcht werden
• autoShim: Standardwert ist true und steuert den nativen cap sync Auto-Konfigurations-Hook

Führe den Sync nach der Config-Änderung erneut aus:

bunx cap sync

Shim während des Bootstraps installieren

Importiere das Plugin über den Standard-Package-Entrypoint und installiere dann den Shim während des App-Bootstraps:

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

await CapacitorPasskey.autoShimWebAuthn();

Danach kann dein bestehender Browser-basierter Passkey code unverändert bleiben.

Falls du den Shim erzwingen oder den konfigurierten Origin zur Laufzeit überschreiben musst, rufe auf:

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

CapacitorPasskey.shimWebAuthn({
  origin: 'https://signin.example.com',
});

Behalte deinen normalen WebAuthn-Flow bei

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

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

Was der Sync für dich patcht

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

• iOS: Associated Domains Entitlements und Xcode-Entitlements-Verknüpfung bei Bedarf
• Android: asset_statements Metadaten und die vom Manifest verwendete generierte Ressource

Native Einrichtung benötigt weiterhin Website-Trust-Files

Das Plugin reduziert den Aufwand auf App-Seite, aber Passkeys hängen weiterhin von den Website-Trust-Files für deine Relying-Party-Domain ab. Du musst weiterhin hosten:

• 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 des Sync patchen, kann diese Website-Trust-Files jedoch nicht für dich erstellen oder hosten.

Andere öffentliche Methoden

Das öffentliche Plugin API stellt zudem die direkten Helper bereit, die in src/definitions.ts:

• await CapacitorPasskey.getConfiguration() gibt das aufgelöste origin, domains, autoShim, und aktuelle platform.
• await CapacitorPasskey.createCredential(...) registriert einen Passkey aus einem JSON-safe WebAuthn-Payload.
• await CapacitorPasskey.getCredential(...) authentifiziert mit einem vorhandenen Passkey aus einem JSON-safe WebAuthn-Payload.
• await CapacitorPasskey.isSupported() gibt an, ob die aktuelle Runtime Passkeys unterstützt.
• await CapacitorPasskey.getPluginVersion() gibt den aktuellen Versionsmarker der nativen Implementierung zurück.

Plattform-Guides

• Erste Schritte
• iOS-Setup
• Android-Setup
• Backend-Hinweise

Wichtiger iOS-Hinweis

Ab iOS 17.4 nutzt das Plugin die client-data im Browser-Stil von API, sodass der konfigurierte HTTPS-Origin in clientDataJSON.

Wichtiger Android-Hinweis

Der Android Credential Manager kann bei konfigurierten Digital Asset Links dieselbe Relying Party und Passkeys wie deine Website nutzen, aber der native Assertion-Origin ist nicht identisch mit einem Browser-Origin. Wenn dein Backend strikt validiert clientDataJSON.origin, stelle sicher, dass neben deiner Website-Origin auch die Android-App-Origin akzeptiert wird.

Vollständige Referenz

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

Weiter mit Using @capgo/capacitor-passkey

Wenn du es nutzt @capgo/capacitor-passkey verwenden Um Authentifizierungs- und Account-Flows zu planen, verbinde es mit @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey, Erste Schritte für die Implementierungsdetails in Erste Schritte, @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 Zwei-Faktor-Authentifizierung für die Implementierungsdetails zur Zwei-Faktor-Authentifizierung.