Saltar al contenido principal
Capgo logo
Volver a plugins
@capgo/capacitor-passkey
Tutoriales
por github.com/Cap-go

Passkey

Mantenga el estilo de navegador de WebAuthn code en Capacitor mientras se manejan llamadas de passkey nativas y parches de host para usted

Descargas/semana

4.8k

GitHub Estrellas

2

Guía

Tutorial sobre Passkey

Usando @capgo/capacitor-passkey

Mantén su estilo de navegador WebAuthn code en una aplicación Capacitor mientras el complemento maneja llamadas de passkey nativas y parches de host nativos.

Estilo de navegador API

@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 compilaciones nativas, el complemento instala un shim para navigator.credentials.create() y navigator.credentials.get(), envía la solicitud a las APIs de passkey de iOS y Android, y devuelve objetos de credenciales como en un navegador a tu aplicación.

Instale y sincronice proyectos nativos

bun add @capgo/capacitor-passkey
bunx cap sync

Configure la aplicación de host una vez

Agregar 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 principal de confianza utilizado por el shim y directo API
  • domains: hostnames adicionales de confianza para parchear en la configuración nativa durante la sincronización
  • autoShim: predeterminado true y controla la configuración nativa cap sync de la función de hook de configuración automática

Ejecuta sincronización nuevamente después de cambiar la configuración:

bunx cap sync

Instala el shim durante el arranque

Importa el plugin desde el punto de entrada estándar del paquete, luego instala el shim durante el arranque de la aplicación:

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

await CapacitorPasskey.autoShimWebAuthn();

Después de eso, tu existente clave de navegador estilo code puede permanecer igual.

Si necesitas forzar el shim o sobrescribir el origen configurado en tiempo de ejecución, llama a:

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

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

Mantén tu flujo normal de WebAuthn

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

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

¿Qué parches de sincronización para ti?

Durante bunx cap sync, el plugin actualiza los proyectos de anfitrión nativos generados:

  • iOS: permisos de dominios asociados y configuración de permisos de Xcode cuando sea necesario
  • Android: asset_statements metadatos y el recurso generado utilizado por el manifiesto

Configuración nativa todavía necesita archivos de confianza de sitio web

El plugin reduce el trabajo en el lado de la aplicación, pero las claves de paso todavía dependen de los archivos de confianza de sitio web para su dominio de partido de confianza. Todavía necesita alojar:

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

El plugin puede parchear los proyectos nativos generados durante la sincronización, pero no puede crear ni alojar esos archivos de confianza de sitio web para usted.

Otros métodos públicos

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

  • await CapacitorPasskey.getConfiguration() devuelve la resolución origin, domains, autoShim, y actual platform.
  • await CapacitorPasskey.createCredential(...) registra una clave de paso a partir de un payload WebAuthn seguro JSON.
  • await CapacitorPasskey.getCredential(...) autentica con una clave de paso existente a partir de un payload WebAuthn seguro JSON.
  • await CapacitorPasskey.isSupported() informa si el runtime actual admite claves de paso.
  • await CapacitorPasskey.getPluginVersion() devuelve la versión actual del marcador de implementación nativa.

Guías de plataforma

Nota importante de iOS

En iOS 17.4 y versiones posteriores, el complemento utiliza el cliente de datos estilo navegador API por lo que el origen HTTPS configurado se refleja en clientDataJSON.

Cautela importante de Android

El Administrador de credenciales de Android puede compartir el mismo proveedor de confianza y claves de acceso como su sitio web cuando se configuran los enlaces de activos digitales, pero el origen de la afirmación nativa no es idéntico a un origen de navegador. Si su backend valida estrictamente clientDataJSON.originAsegúrese de que acepte el origen de la aplicación de Android junto con el origen de su sitio web.

Referencia completa