Passkey plugin Capacitor

Utiliser @capgo/capacitor-passkey

Conservez votre style de navigateur WebAuthn code dans une application Capacitor tout en laissant le plugin gérer les appels de clés de passe native et la mise à jour de l'hôte native.

Style de navigateur API

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

Sur les builds natives, le plugin installe un shim pour navigator.credentials.create() et navigator.credentials.get()Envoie la demande vers les APIs de passkey iOS et Android, et renvoie des objets de credenciaux similaires à ceux d'un navigateur à votre application.

Installer et synchroniser les projets natives

bun add @capgo/capacitor-passkey
bunx cap sync

Configurer l'application d'hôte une 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 le plugin de configuration fait

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

• origin: origine HTTPS primaire utilisée par le shim et directement API
• domainsAjoutez des hôtes de tiers pour les synchroniser avec la configuration native.
• autoShim: par défaut true et contrôle la mise à jour native cap sync l'invite de configuration automatique

Run sync again after changing the config:

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 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 synchronisent pour vous

Pendant 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 le fichier de ressource généré utilisé 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 pour votre domaine de partie de confiance. Vous devez toujours 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(...) authentifie avec une passkey existante à partir d'un payload WebAuthn sécurisé en 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

• Getting started
• Configuration iOS
• Configuration Android
• Remarques sur le serveur

Note important iOS

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

Alerte importante Android

Le gestionnaire de crédits Android peut partager le même partenaire de confiance et les clés de passe que votre site web lorsque les liens de biens numériques sont configurés, mais l'origine d'assertion native n'est pas identique à une origine de navigateur. Si votre serveur back-end valide strictement clientDataJSON.originAssurez-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 L'utilisation de @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, Prise en main pour les détails d'implémentation dans Prise en main, @capgo/capacitor-connexion-social pour les détails d'implémentation dans @capgo/capacitor-social-login, @capgo/capacitor-native-biometrique 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.