Clé d’accès Plugin Capacitor

Utilisation de @capgo/capacitor-passkey

Conservez votre code WebAuthn de type navigateur dans une app Capacitor pendant que le plugin gère les appels passkey natifs et le patch de l'hôte natif.

API de type navigateur

@capgo/capacitor-passkey 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 });

Sur les builds natifs, le plugin installe un shim pour navigator.credentials.create() et navigator.credentials.get(), transmet la requête aux API passkey d'iOS et d'Android, et renvoie à votre app des objets credentials similaires à ceux du navigateur.

Installer et synchroniser les projets natifs

bun add @capgo/capacitor-passkey
bunx cap sync

Configurer l'app hôte une seule fois

Ajouter la config 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;

Rôle de la config du plugin

La config est lue depuis plugins.CapacitorPasskey dans capacitor.config.*.

• origin: l'origine HTTPS de la relying-party primaire utilisée par le shim et API en direct
• domains: hôtes relying-party supplémentaires à patcher dans la config native lors de la sync
• autoShim: par défaut true et contrôle le natif cap sync hook d'auto-configuration

Relancez la sync après avoir modifié la config :

bunx cap sync

Installer le shim lors du bootstrap

Importez le plugin depuis l'entrypoint standard du package, puis installez le shim lors du bootstrap de l'app :

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

await CapacitorPasskey.autoShimWebAuthn();

Après cela, votre code de type navigateur actuel peut rester inchangé.

Si vous devez forcer le shim ou surcharger l'origine configurée au runtime, appelez :

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

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

Gardez votre flux WebAuthn habituel

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

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

Ce que la sync patch pour vous

Pendant bunx cap sync, le plugin met à jour les projets natifs générés :

• iOS : entitlements des domaines associés et configuration des entitlements Xcode si nécessaire
• Android : asset_statements métadonnées et la ressource générée utilisée par le manifeste

Native setup still needs website trust files

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 relying-party. Vous devez toujours héberger :

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

Le plugin peut patcher les projets natifs générés lors du sync, mais il ne peut pas créer ou héberger ces fichiers de confiance 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 l'actuel platform.
• await CapacitorPasskey.createCredential(...) enregistre une passkey à partir d'un payload WebAuthn compatible JSON.
• await CapacitorPasskey.getCredential(...) authentifie avec une passkey existante à partir d'un payload WebAuthn compatible JSON.
• await CapacitorPasskey.isSupported() indique si l'environnement d'exécution actuel supporte les passkeys.
• await CapacitorPasskey.getPluginVersion() renvoie le marqueur de version de l'implémentation native actuelle.

Guides par plateforme

• Prise en main
• Configuration iOS
• Configuration Android
• Notes backend

Note importante pour iOS

Sur iOS 17.4 et versions ultérieures, le plugin utilise le client-data API de type navigateur afin que l'origine HTTPS configurée soit reflétée dans clientDataJSON.

Attention particulière pour Android

Android Credential Manager peut partager la même relying party et les mêmes passkeys que votre site web si les Digital Asset Links sont configurés, mais l'origine de l'assertion native n'est pas identique à une origine de navigateur. Si votre backend valide strictement clientDataJSON.origin, assurez-vous qu'il accepte l'origine de l'application Android en plus de celle de votre site web.

Référence complète

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

Continuer après l'utilisation de @capgo/capacitor-passkey

Si vous utilisez Utilisation de @capgo/capacitor-passkey pour planifier les flux d'authentification et de compte, le connecter à @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-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 de l'authentification à deux facteurs.