Usando @capgo/capacitor-passkey

Mantén su estilo de navegador WebAuthn code en una aplicación Capacitor mientras el plugin 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 utiliza en la web:

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

En compilaciones nativas, el plugin instala un shim para navigator.credentials.create() y navigator.credentials.get(), envía la solicitud a las API de passkey de iOS y Android, y devuelve objetos de credenciales como en el navegador a tu aplicación.

Instalar y sincronizar proyectos nativos

bun add @capgo/capacitor-passkey
bunx cap sync

Configurar 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 de HTTPS primario de la parte de confianza utilizada por el shim y directo API
domains: nombres de host de la parte de confianza adicionales para parchear en la configuración nativa durante la sincronización
autoShim: se establece por defecto true y controla la parte de configuración nativa cap sync hook de configuración automática

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

bunx cap sync

Instalar el shim durante el arranque

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

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

await CapacitorPasskey.autoShimWebAuthn();

Después de eso, su clave de acceso existente de estilo de navegador code puede seguir siendo la misma.

Si necesita forzar el shim o sobreescribir el origen configurado en tiempo de ejecución, llame a:

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

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

Mantenga su flujo de autenticación WebAuthn normal

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

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

Qué parches de sincronización para usted

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

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

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

El plugin reduce el trabajo del lado de la aplicación, pero las claves de acceso todavía dependen de los archivos de confianza de sitio web para su dominio de parte 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 el valor resuelto origin, domains, autoShim, y actual platform.
await CapacitorPasskey.createCredential(...) registra una clave de acceso desde un payload seguro WebAuthn JSON.
await CapacitorPasskey.getCredential(...) autentica con una clave de acceso existente desde un payload seguro WebAuthn JSON.
await CapacitorPasskey.isSupported() informa si el tiempo de ejecución actual admite claves de acceso.
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 posteriores, el complemento utiliza el cliente de datos estilo navegador API por lo que el origen HTTPS configurado se refleja en clientDataJSON.

Importante advertencia 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 servidor de backend clientDataJSON.originVerifique que acepte el origen de la aplicación de Android junto con el origen de su sitio web.

Referencia completa

GitHub: https://github.com/Cap-go/capacitor-passkey/
Documentación: /docs/plugins/passkey/

Siga adelante desde Usando @capgo/capacitor-passkey

Si está utilizando Usando @capgo/capacitor-passkey para planificar la autenticación y los flujos de cuenta, conecte con @capgo/capacitor-passkey para los detalles de implementación en @capgo/capacitor-passkey, Inicio para los detalles de implementación en Inicio, @capgo/capacitor-social-login para los detalles de implementación en @capgo/capacitor-social-login, @capgo/capacitor-native-biometric para los detalles de implementación en @capgo/capacitor-native-biometric, y Autenticación en dos factores para los detalles de implementación en Autenticación en dos factores.

Passkey

Tutoriales sobre Passkey