Utilisation de @capgo/capacitor-passkey

Conservez votre style de navigateur WebAuthn code dans une application Capacitor tout en laissant le plugin gérer les appels de la clé de pass native et le patchage de l'hôte natif.

Style de navigateur API

@capgo/capacitor-passkey Le __CAPGO_KEEP_0__ 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 natives, le plugin installe un shim pour navigator.credentials.create() et navigator.credentials.get(), transmet la demande vers les API de clés de pass iOS et Android, et retourne des objets de credenciaux similaires à ceux du navigateur à votre application.

Installer et synchroniser les projets natifs

bun add @capgo/capacitor-passkey
bunx cap sync

Configurer l'application hôte une seule fois

Ajouter 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 fait la configuration du plugin

La configuration est lue à partir de plugins.CapacitorPasskey dans capacitor.config.*.

origin: origine HTTPS primaire utilisée par le shim et directement par API
domains: hôtes supplémentaires de l'application de confiance à intégrer dans la configuration native lors de la synchronisation
autoShim: par défaut true et contrôle la mise en configuration native automatique cap sync l'hook de mise en configuration native 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();

Après cela, votre clé de passe existante de style navigateur code peut rester la 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 patchs de synchronisation pour vous

Lorsque bunx cap sync, le plugin met à jour les projets de hôte natifs 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 les ressources générées utilisées par le manifest

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 clés de passe dépendent toujours des fichiers de confiance du site web pour votre domaine de partie de confiance. Vous avez toujours besoin de héberger :

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

Le plugin peut corriger les projets natifs 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 assistants directs définis dans src/definitions.ts:

await CapacitorPasskey.getConfiguration() renvoie la valeur résolue origin, domains, autoShim, et actuel 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-data de style navigateur API donc l'origine HTTPS configurée est reflétée dans clientDataJSON.

Avertissement Android important

Le gestionnaire de clés Android peut partager la même partie de confiance et les mots de passe partagés que votre site web lorsque les liens d'actif numérique sont configurés, mais l'origine d'affirmation native n'est pas identique à une origine de navigateur. Si votre serveur valide strictement clientDataJSON.originAssurez-vous que votre serveur accepte l'origine de l'application Android aux côtés de l'origine de votre site web.

Référence complète

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

Passkey

Tutoriel sur la Clé de Pass