Utilisez @capgo/capacitor-passkey

Keep your browser-style WebAuthn code in a Capacitor app while the plugin handles native passkey calls and native host patching.

Browser-style API

@capgo/capacitor-passkey Le style de navigateur de WebAuthn conserve le même flux WebAuthn que vous utilisez déjà sur le web :

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

Dans les builds natifs, le plugin installe un shim pour navigator.credentials.create() et navigator.credentials.get()transmet le requête vers les API de passkey iOS et Android, et retourne des objets de credenciaux similaires à ceux d'un navigateur à votre application.

Installez et synchronisez les projets natifs

bun add @capgo/capacitor-passkey
bunx cap sync

Configurez l'application d'hôte une fois

Ajoutez la configuration du plugin dans capacitor.config.ts ou 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;

Ce que la configuration du plugin fait

La configuration est lue depuis plugins.CapacitorPasskey en capacitor.config.*.

origin: origine HTTPS primaire de la partie dépendante utilisée par le shim et l’API direct
domains: hôtes de la partie dépendante supplémentaires à intégrer dans la configuration native lors de la synchronisation
autoShim: par défaut true et contrôle la prise en charge native cap sync l'hook de configuration automatique

Exécutez à nouveau la synchronisation après avoir modifié la configuration :

bunx cap sync

Installez le shim lors du démarrage

Importez le plugin à partir de l'entrée de package standard, puis installez le shim lors du démarrage de l'application :

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

await CapacitorPasskey.autoShimWebAuthn();

After cela, votre passkey existant de style navigateur code peut rester le même.

Si vous devez forcer le shim ou définir l'origine configurée en temps de exécution, appelez :

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

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

Conservez votre flux WebAuthn normal

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

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

Quels correctifs de synchronisation vous concernent

Lors de bunx cap sync, le plugin met à jour les projets de hôte natif générés :

iOS : autorisations de domaine associées et câblage d'autorisations Xcode lorsqu'il le faut
Android : asset_statements méta-données et le fichier de ressource généré utilisé par le manifeste

La mise en place native nécessite toujours des fichiers de confiance du site Web

Le plugin réduit le travail côté application, mais les passkeys dépendent toujours des fichiers de confiance du site Web pour votre domaine de partie dépendante. Vous avez toujours besoin d'héberger :

https://your-domain/.well-known/apple-app-site-association
https://your-domain/.well-known/assetlinks.json

Le plugin peut corriger les projets de hôte natif générés lors de la synchronisation, mais il ne peut pas créer ou héberger ces fichiers de confiance du site Web pour vous.

Autres méthodes publiques

Le plugin public API expose également les helpers directs définis dans src/definitions.ts:

await CapacitorPasskey.getConfiguration() renvoie la valeur résolue origin, domains, autoShim, et actuelle platform.
await CapacitorPasskey.createCredential(...) enregistre une clé de passe à partir d'un payload WebAuthn sécurisé JSON.
await CapacitorPasskey.getCredential(...) s'authentifie avec une clé de passe existante à partir d'un payload WebAuthn sécurisé JSON.
await CapacitorPasskey.isSupported() indique si le runtime actuel prend en charge les clés de passe.
await CapacitorPasskey.getPluginVersion() renvoie la version de marque de l'implémentation native actuelle.

Guides de plateforme

Note importante iOS

Sur iOS 17.4 et versions ultérieures, le plugin utilise le client de données de style navigateur API donc l'origine HTTPS configurée est reflétée dans clientDataJSON.

Alerte importante Android

Le gestionnaire de crédentials Android peut partager la même partie de confiance et les clés de passe comme votre site web lorsque les liens de biens numériques sont configurés, mais l'origine d'affirmation native n'est pas identique à une origine de navigateur. Si votre arrière-plan valide strictement clientDataJSON.origin, assurez-vous qu'il accepte l'origine de l'application Android en plus de l'origine de votre site web.

Référence complète

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

Continuez à partir de l'utilisation de @capgo/capacitor-passkey

Si vous utilisez En utilisant @capgo/capacitor-passkey pour planifier l'authentification et les flux de compte, connectez-l’avec à @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey Démarrage pour les détails d'implémentation dans Démarrage à @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-social-login à @capgo/capacitor-native-biometric pour les détails d'implémentation dans @capgo/capacitor-native-biometric, et Authentification à deux facteurs pour les détails d'implémentation dans Authentification à deux facteurs.

Passkey

Tutoriel sur Passkey