Cómo agregar autenticación a una aplicación de Capacitor (2026)

Para agregar autenticación a una aplicación Capacitor, elija una fuente de identidad (su propio backend, un servicio hospedado como Firebase o Supabase, un proveedor OIDC como Auth0, Okta o Entra ID, o una biblioteca autoalojada como Better Auth), utilice plugins nativos para cualquier cosa que abra una página de inicio de sesión de proveedor, verifique tokens en un servidor y almacene la sesión resultante en la Keychain o Keystore. Las claves de acceso y las biométricas entonces hacen que el próximo inicio de sesión sea rápido.

Esta guía mapea cada opción común a la correspondiente extensión Capacitor y flujo, con code para las partes que son iguales en cada aplicación: la llamada de inicio de sesión, la verificación de tokens, el almacenamiento de sesión y el desbloqueo biométrico. Está actualizado para Capacitor 8 en octubre de 2026. Cada proveedor tiene su propia guía paso a paso enlazada a continuación.

El flujo de autenticación que cada aplicación Capacitor termina con

No importa qué proveedor elijas, la forma es la misma:

1. Identifica the user: native social sheet, provider login page in the system browser, passkey prompt, or a form that posts email and password.
2. Obtén una prueba: un token de identidad, un token de autorización code, o un token de sesión de tu servidor de autenticación.
3. Verifica en el servidor: verifica la firma, emisor, audiencia y vencimiento, y luego crea o encuentra al usuario.
4. Emite una sesión: tu propio token o los tokens del proveedor, con una estrategia de refresco.
5. Almacénalo de manera segura en el dispositivo y adjúntalo a API llamadas.
6. Desbloquea rápidamente La próxima vez con autenticación biométrica, y manejar la salida y eliminación de cuenta.

Los pasos 1 y 2 cambian con el proveedor. Los pasos 3 a 6 son su responsabilidad en cada opción excepto BaaS alojado en su totalidad, donde el SDK hace la mayoría de las cosas.

¿Por qué las páginas de inicio de sesión WebView se rompen

Una aplicación Capacitor ejecuta su web code en un WKWebView (iOS) o Android WebView con un origen local (capacitor://localhost o https://localhostCargando la página de inicio de sesión del proveedor dentro de ese WebView causa tres problemas:

• Google devuelve disallowed_useragent y se niega a mostrar la página.
• La aplicación no puede probar que la página es el proveedor real, por lo que RFC 8252 recomienda a las aplicaciones nativas que utilicen el navegador del sistema.
• Una redirección de página completa navega fuera de tu aplicación empaquetada y pierde estado.

Así que cada flujo a continuación utiliza un SDK nativo (Apple, Google, Facebook) o una sesión de navegador del sistema ("ASWebAuthenticationSession en iOS, Chrome Custom Tabs en Android) que devuelve a la aplicación a través de un esquema personalizado.

Sus opciones a la vista

Inicio de sesión social nativo (Apple, Google, Facebook)

Un plugin cubre los tres grandes proveedores de consumidores más un motor de OAuth2 genérico:

bun add @capgo/capacitor-social-login
bunx cap sync

import { SocialLogin } from '@capgo/capacitor-social-login';

await SocialLogin.initialize({
  apple: { clientId: 'com.example.app' },
  google: {
    webClientId: 'WEB_CLIENT_ID.apps.googleusercontent.com',
    iOSClientId: 'IOS_CLIENT_ID.apps.googleusercontent.com',
  },
});

const { result } = await SocialLogin.login({ provider: 'google', options: {} });
// send result.idToken to your server

Deshabilite los proveedores que no utilice en capacitor.config.ts (plugins.SocialLogin.providers) por lo tanto, sus SDK no se compilan en la aplicación. También elimina la solicitud de permiso de ID de publicidad de Facebook de SDK si no se utiliza Facebook.

Cada proveedor tiene una configuración nativa: Apple necesita la capacidad en Xcode y un ID de Servicio para Android, Google necesita huellas digitales SHA-1 y un esquema de URL de cliente invertido. El Apple y Google Las guías recorren cada paso y los errores comunes.

Autenticación empresarial con OAuth 2.0 y OpenID Connect

Para Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin o su propio servidor OIDC, utilice el plugin’s oauth2 proveedor. Corre el flujo de autorización code con PKCE en ASWebAuthenticationSession en iOS y en Custom Tabs en Android cuando establezca androidUseCustomTabs: true:

await SocialLogin.initialize({
  oauth2: {
    corp: {
      issuerUrl: 'https://sso.example.com/realms/mobile', // OIDC discovery
      clientId: 'mobile-app',
      redirectUrl: 'com.example.app://oauth/corp',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      androidUseCustomTabs: true,
    },
  },
});

const { result } = await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'corp' },
});

Puede registrar varios proveedores en el mismo mapa y elegir uno con providerId, que es cómo las aplicaciones B2B multi-tenant permiten a cada cliente traer su propio IdP. El plugin también maneja la actualización de tokens (SocialLogin.refresh), el cierre de sesión con id_token_hint, y un wrapper compatible con Ionic Auth Connect (SocialLoginAuthConnect) para equipos que migran de Auth Connect. Guías de proveedores: Auth0, Okta, Inicia sesiónPara el contexto de protocolo de fondo, consulte 5 pasos para implementar OAuth2 en aplicaciones Capacitor.

Servidores alojados: Firebase y Supabase

Si su datos ya viven en Firebase o Supabase, utilice su autenticación para que las reglas de seguridad y la seguridad de nivel de fila funcionen sin necesidad de un enlace adicional.

• SupabaseObtén un token de ID con el plugin de inicio de sesión social y llama supabase.auth.signInWithIdToken({ provider: 'google', token })Supabase verifica y devuelve una sesión. Configuración completa: Supabase con Capacitor Inicio de sesión social.
• Firebase: o utilice @capgo/capacitor-firebase-authentication, que envuelve los SDK nativos de autenticación de Firebase, o obtenga un token de ID con Inicio de sesión social y cree un credencial de Firebase a partir de él en el JS SDK. Consulte el Firebase Google login docs.

Autenticación autoalojada: Mejor Autenticación

Mejor Autenticación es una biblioteca de autenticación de TypeScript de código abierto que almacena a los usuarios en su propia base de datos. Funciona en Capacitor una vez que confíe en los orígenes de la aplicación y cambie a tokens de portador, porque las cookies de sitio cruzado son inconfiables en WKWebView. La autenticación social se realiza a través del plugin nativo y un intercambio de token de ID. Paso a paso: Cómo usar Mejor Autenticación en Capacitor aplicaciones.

Claves de acceso

Las claves de acceso sustituyen a las contraseñas con una pareja de claves almacenadas en iCloud Keychain o Google Password Manager. Necesitan que su aplicación esté asociada con el dominio de su sitio web (apple-app-site-association en iOS, assetlinks.json en Android) y un servidor WebAuthn.

@capgo/capacitor-passkey te permite mantener la autenticación WebAuthn estándar code. Configura la parte que confía en capacitor.config.tsllama a la simulación una vez al arranque, y navigator.credentials.create() y .get() son redirigidos a las APIs de passkey nativas:

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

await CapacitorPasskey.autoShimWebAuthn();

// existing WebAuthn code keeps working
const assertion = await navigator.credentials.get({
  publicKey: requestOptionsFromServer,
});

Las bibliotecas como Better Auth, y proveedores hospedados como Auth0 y Okta, pueden actuar como el servidor WebAuthn. Consulte la página del plugin de passkey.

Email y contraseña con su propio backend

No se necesita ningún plugin, es solo fetch. El trabajo se realiza en el servidor: hash con Argon2id o bcrypt, limitar intentos de inicio de sesión, enviar correos electrónicos de verificación y restablecimiento, y soportar la eliminación de cuentas. Abra los enlaces de restablecimiento y verificación en la aplicación con Enlaces Universales y Enlaces de Aplicación, para que el enlace aterrice en el lugar correcto en un teléfono. A menos que tenga una razón para poseer todo eso, una biblioteca como Better Auth o un servicio hospedado le da las mismas características con menos riesgo.

Verifique los tokens en el servidor, siempre

Las comprobaciones del lado del cliente pueden ser bypassadas. Independientemente del proveedor, el servidor debe verificar el token antes de crear una sesión:

import { createRemoteJWKSet, jwtVerify } from 'jose';

type IssuerConfig = {
  jwks: ReturnType<typeof createRemoteJWKSet>;
  issuer: string | string[];
  audience: string[];
};

const issuers: Record<'google' | 'apple', IssuerConfig> = {
  google: {
    jwks: createRemoteJWKSet(new URL('https://www.googleapis.com/oauth2/v3/certs')),
    issuer: ['https://accounts.google.com', 'accounts.google.com'],
    audience: ['WEB_CLIENT_ID.apps.googleusercontent.com', 'IOS_CLIENT_ID.apps.googleusercontent.com'],
  },
  apple: {
    jwks: createRemoteJWKSet(new URL('https://appleid.apple.com/auth/keys')),
    issuer: 'https://appleid.apple.com',
    audience: ['com.example.app', 'com.example.app.signin'],
  },
};

export async function verifyIdToken(provider: 'google' | 'apple', idToken: string) {
  const cfg = issuers[provider];
  const { payload } = await jwtVerify(idToken, cfg.jwks, {
    issuer: cfg.issuer,
    audience: cfg.audience,
  });
  return payload; // use payload.sub as the stable provider user ID
}

Claves de los usuarios en el proveedor’s sub (Sólo enlace cuentas por correo electrónico cuando el proveedor lo marque como verificado)email_verified: trueLos tokens de inicio de sesión limitados de Meta no incluyen esa afirmación.

Almacena la sesión de manera segura

localStorage y las Capacitor Preferencias son archivos de texto plano. Coloque tokens de larga duración en el almacenamiento cifrado de Keychain (iOS) o Keystore (Android). @capgo/capacitor-native-biometric has simple setData, getData y deleteData métodos para eso:

bun add @capgo/capacitor-native-biometric
bunx cap sync

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

export const sessionStore = {
  async save(token: string) {
    await NativeBiometric.setData({ key: 'session.token', value: token });
  },
  async load(): Promise<string | null> {
    try {
      const { value } = await NativeBiometric.getData({ key: 'session.token' });
      return value;
    } catch {
      return null;
    }
  },
  async clear() {
    await NativeBiometric.deleteData({ key: 'session.token' }).catch(() => {});
  },
};

Mantén tokens de acceso de corta duración y refresca con un token de refresco o una sesión del servidor. guía de almacenamiento de tokens seguro cubre la rotación y la revocación en mayor profundidad.

Biometría: desbloquear, no identidad

El Face ID y el dedo solo demuestran que la persona que sostiene el teléfono puede desbloquearlo. Utilícelos para bloquear el acceso a una sesión almacenada:

import { AccessControl, NativeBiometric } from '@capgo/capacitor-native-biometric';

// after a real login, offer biometric unlock
await NativeBiometric.setData({
  key: 'session.refresh',
  value: refreshToken,
  accessControl: AccessControl.BIOMETRY_ANY,
});

// next app start
const { value } = await NativeBiometric.getSecureData({
  key: 'session.refresh',
  reason: 'Unlock your account',
});
// exchange `value` with your server for a fresh access token

Con accessControl establecido, el sistema libera el valor solo después de un verificación biométrica exitosa, por lo que la protección se enuncia por la caja de claves o el almacén de claves, no por JavaScript. Páralo con la expiración de la sesión del lado del servidor y, para aplicaciones de alto riesgo, la detección de raíz y jailbreak. Más en Autenticación biométrica en aplicaciones Capacitor.

Elige un método

Reglas de App Store y Play que afectan la autenticación

• Apple 4.8 Servicios de inicio de sesiónIncorporar inicio de sesión con Apple como opción principal requiere una alternativa enfocada en la privacidad. El inicio de sesión con Apple la satisface.
• Apple 5.1.1(v)La cuenta de la cuenta se elimina en la aplicación y se deben revocar los tokens de inicio de sesión con Apple. cumplimiento de la eliminación de cuenta.
• eliminación de cuenta de Google Play: las aplicaciones con cuentas deben ofrecer la eliminación en la aplicación y a través de un enlace web declarado en el Console de Play.
• Acceso del revisor: give reviewers a working demo account. If login is SSO only, provide a test tenant user.
• Xcode 26: App Store Connect requiere construcciones realizadas con Xcode 26 e iOS 26 SDK desde abril de 2026, así que actualiza antes de enviar una versión que agregue nuevas capacidades de autenticación.

Envía cambios de autenticación de manera segura

Los errores de autenticación bloquean a todos los usuarios, así que querrás solucionarlos rápidamente. Los cambios nativos (permisos, esquemas de URL, filtros de intención) requieren una construcción de tienda. Todo en TypeScript, como la configuración del proveedor, los alcances, el manejo de errores y la interfaz de usuario, se pueden enviar con Capgo actualizaciones en vivo y se deshaga si algo se rompe. Capgo Construcción genera los binarios iOS y Android firmados en la nube cuando necesites una nueva versión nativa.

Próximos pasos

Elige tu proveedor y sigue la guía correspondiente:

• Inicia sesión con Apple
• Inicia sesión con Google
• Auth0
• Okta
• Azure Active Directory
• Mejor Autenticación
• Social Login plugin documentation