Passkey plugin de Capacitor

Usando @capgo/capacitor-passkey

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

Browser-style 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 });

On builds nativos, 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 su aplicación.

Instale y sincronice proyectos nativos

bun add @capgo/capacitor-passkey
bunx cap sync

Configure la aplicación de host una vez

Agregue la configuración del complemento 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: agregar hostnames de terceros para parchear en la configuración nativa durante la sincronización
• autoShim: predeterminado a true y controla la configuración nativa cap sync hook de configuración automática

Run sync again after changing the config:

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, su passkey de navegador existente code puede seguir igual.

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

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

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

Conserva tu flujo WebAuthn normal

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

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

¿Qué parches sincroniza para ti?

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

Native setup still needs website trust files

La extensión reduce el trabajo en el lado del aplicativo, pero las claves de acceso todavía dependen de los archivos de confianza del sitio web para tu dominio de parte confiable. Todavía necesitas hospedar:

• 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 por ti.

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 WebAuthn seguro JSON.
• await CapacitorPasskey.getCredential(...) autentica con una clave de acceso existente desde un payload WebAuthn seguro JSON.
• await CapacitorPasskey.isSupported() indica si el tiempo de ejecución actual admite claves de acceso.
• await CapacitorPasskey.getPluginVersion() devuelve la marca de versión de implementación nativa actual.

Guías de plataforma

• Configuración inicial
• iOS setup
• Configuración de Android
• Nota del backend

Nota importante de iOS

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

Nota importante de Android

El Administrador de credenciales de Android puede compartir la misma parte interesada y claves de acceso como tu 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 tu servidor valida estrictamente clientDataJSON.originAsegúrese de que acepte el origen de la aplicación Android junto con el origen de su sitio web.

Referencia completa

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

Sigue adelante desde Usando @capgo/capacitor-passkey

Si estás 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, Getting Started para los detalles de implementación en Inicio, @capgo/capacitor-login-social para los detalles de implementación en @capgo/capacitor-social-login, @capgo/capacitor-nativo-biometrico 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.