Passkey plugin Capacitor

Uso de @capgo/capacitor-passkey

Mantén tu code WebAuthn estilo navegador en una app Capacitor mientras el plugin gestiona las llamadas nativas de passkey y el patching del host nativo.

API estilo navegador

@capgo/capacitor-passkey mantiene el mismo flujo de WebAuthn que ya usas en la web:

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

En Native Build, el plugin instala un shim para navigator.credentials.create() y navigator.credentials.get(), redirige la solicitud a las APIs de passkey de iOS y Android, y devuelve objetos de credenciales similares a los del navegador a tu app.

Instala y sincroniza proyectos nativos

bun add @capgo/capacitor-passkey
bunx cap sync

Configura la app host una vez

Añade la configuración del plugin en capacitor.config.ts o 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;

Qué hace la configuración del plugin

La configuración se lee desde plugins.CapacitorPasskey en capacitor.config.*.

• origin: origen HTTPS de la parte confiable (relying-party) principal usado por el shim y API directo
• domains: hostnames de relying party adicionales para parchear en la config nativa durante el sync
• autoShim: por defecto es true y controla el nativo cap sync hook de autoconfiguración

Ejecuta sync de nuevo tras cambiar la config:

bunx cap sync

Instala el shim durante el bootstrap

Importa el plugin desde el entrypoint estándar del paquete, luego instala el shim durante el bootstrap de la app:

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

await CapacitorPasskey.autoShimWebAuthn();

Después de eso, tu code actual de passkey estilo navegador puede seguir igual.

Si necesitas forzar el shim o sobrescribir el origin configurado en runtime, llama a:

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

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

Mantén tu flujo WebAuthn normal

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

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

Lo que sync parchea por ti

Durante bunx cap sync, el plugin actualiza los proyectos nativos generados:

• iOS: entitlements de associated domains y configuración de Xcode si es necesario
• Android: asset_statements metadatos y el recurso generado utilizado por el manifest

Native setup still needs website trust files

El plugin reduce el trabajo en la app, pero las passkeys dependen de los archivos de confianza de tu dominio relying-party. Debes alojar:

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

El plugin puede parchear los proyectos nativos durante el sync, pero no puede crear ni alojar esos archivos de confianza por ti.

Otros métodos públicos

El plugin público API también expone los helpers directos definidos en src/definitions.ts:

• await CapacitorPasskey.getConfiguration() devuelve el valor resuelto origin, domains, autoShim, y el actual platform.
• await CapacitorPasskey.createCredential(...) registra una passkey desde un payload WebAuthn compatible con JSON.
• await CapacitorPasskey.getCredential(...) autentica con una passkey existente mediante un payload WebAuthn compatible con JSON.
• await CapacitorPasskey.isSupported() informa si el runtime actual es compatible con passkeys.
• await CapacitorPasskey.getPluginVersion() devuelve el marcador de la versión actual de la implementación nativa.

Guías por plataforma

• Primeros pasos
• Configurar iOS
• Configuración de Android
• Notas del backend

Nota importante para iOS

En iOS 17.4 y versiones posteriores, el plugin utiliza el client-data API estilo navegador para que el origen HTTPS configurado se refleje en clientDataJSON.

Advertencia importante para Android

Android Credential Manager puede compartir el mismo relying party y las mismas passkeys que tu sitio web cuando se configuran los Digital Asset Links, pero el origen de la aserción nativa no es idéntico al de un navegador. Si tu backend valida estrictamente clientDataJSON.origin, asegúrate de que acepte el origen de la app de Android además del de tu sitio web.

Referencia completa

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

Continúa desde Uso de @capgo/capacitor-passkey

Si estás usando Uso de @capgo/capacitor-passkey para planificar los flujos de autenticación y de cuenta, conéctalo con @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey, Primeros pasos para los detalles de implementación en Primeros pasos, @capgo/capacitor-social-login para los detalles de implementación en @capgo/capacitor-social-login, @capgo/capacitor-native-biometric para el detalle de implementación en @capgo/capacitor-native-biometric, y Autenticación de dos factores para el detalle de implementación en la autenticación de dos factores.