Utilisation de @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 permet de conserver 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 });

Sur les builds natifs, le plugin installe un shim pour navigator.credentials.create() et navigator.credentials.get()et envoie la demande à l'API passkey iOS et Android, puis renvoie des objets de credenciaux similaires à ceux du navigateur à votre application.

Installez et synchronisez les projets natifs

bun add @capgo/capacitor-passkey
bunx cap sync

Configurez l'application 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 fait la configuration du plugin

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

origin: origine HTTPS primaire de l'entreprise de confiance utilisée par le shim et direct API
domains: ajoutez d'autres hôtes de tiers pour les intégrer dans la configuration native lors de la synchronisation
autoShim: par défaut true et contrôle l'hameçonnage auto de la configuration native cap sync Hook de configuration auto

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

bunx cap sync

Installez le shim lors du démarrage du bootstrap

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 à la place à l'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 vous sont proposés

Lors de la synchronisation bunx cap syncLes mises à jour du plugin mettent à jour les projets de hôte natif générés :

iOS : les autorisations de domaine associées et les autorisations Xcode lorsqu'elles sont nécessaires
Android : asset_statements les métadonnées et les ressources générées utilisées par le manifeste

La mise en place native nécessite toujours les 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 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.

Les autres méthodes publiques

La méthode publique du plugin API expose également les assistants directs définis dans src/definitions.ts:

await CapacitorPasskey.getConfiguration() renvoie la résolution origin, domains, autoShimet 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 ultérieur, le plugin utilise le client-data de style navigateur API donc l'origine HTTPS configurée est reflétée dans clientDataJSON.

Caveat Android important

Le gestionnaire de clés de passe Android peut partager la même partie prenante dépendante et les clés de passe 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 navigateur. Si votre backend valide strictement clientDataJSON.originAssurez-vous qu'il accepte l'origine de l'application Android ainsi que votre origine du 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 L'utilisation de @capgo/capacitor-passkey pour planifier l'authentification et les flux de compte, connectez-le avec @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey, Prise en main pour les détails d'implémentation dans Getting Started, @capgo/capacitor-connexion-social pour les détails d'implémentation dans @capgo/capacitor-connexion-social, @capgo/capacitor-authentification-native pour les détails d'implémentation dans @capgo/capacitor-authentification-native, et L'authentification à deux facteurs pour les détails d'implémentation dans L'authentification à deux facteurs.

Passkey

Tutoriel sur la clé de passe