Añada Login a su aplicación Ionic React con Capacitor

Esta guía muestra cómo integrar Auth0 en una aplicación de Ionic React y Capacitor mediante el SDK de Auth0 para React.

Usa la IA para integrar Auth0

Si usas un asistente de programación con IA como Claude Code, Cursor o GitHub Copilot, puedes añadir la autenticación de Auth0 automáticamente en cuestión de minutos usando agent skills.

Primero, instala las agent skills de Auth0:

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-ionic-react

Luego, pídele a tu asistente de IA:

Add Auth0 authentication to my Ionic React app

Tu asistente de IA creará automáticamente tu aplicación de Auth0, obtendrá las credenciales, instalará el SDK de Auth0 para React y los plugins de Capacitor, configurará el deep linking e implementará los flujos de inicio y cierre de sesión con integración con el navegador nativo. Obtén más información sobre Auth0 agent skills.

​

Primeros pasos

Este inicio rápido muestra cómo añadir la autenticación de Auth0 a una aplicación de Ionic React con Capacitor. Crearás una aplicación preparada para dispositivos móviles con funciones de inicio de sesión, cierre de sesión y perfil de usuario mediante el SDK de Auth0 para React y la integración con el navegador nativo de Capacitor.

1. Crear un proyecto nuevo

   Crea una nueva aplicación de Ionic React con Capacitor

   npx ionic start auth0-ionic-react tabs --type=react --capacitor
   

   Abre el proyecto

   cd auth0-ionic-react
   

   Asegúrate de usar el paquete @ionic/cli (no el paquete ionic obsoleto). Si aparece algún error relacionado con --npm-client durante la creación del proyecto, actualiza tu CLI:

   npm uninstall -g ionic
   npm i -g @ionic/cli
   

   Si ya tienes una aplicación de Ionic React, asegúrate de que Capacitor esté habilitado. Puedes agregarlo con ionic integrations enable capacitor y luego npx cap init.

2. Instala el SDK de React para Auth0 y los complementos de Capacitor

   La plantilla inicial de Ionic puede generar react@19.0.0, que no es compatible con el SDK de React de Auth0. Primero, asegúrate de tener una versión compatible de React:

   npm install react@^19.0.1 react-dom@^19.0.1
   

   Luego, instala el SDK de Auth0 y los complementos de Capacitor:

   npm install @auth0/auth0-react @capacitor/browser @capacitor/app && npx cap sync
   

   • @auth0/auth0-react: Proporciona hooks y componentes de React para la autenticación con Auth0
   • @capacitor/browser: Abre la página de Login en el navegador del sistema del dispositivo (SFSafariViewController en iOS, Chrome Custom Tabs en Android)
   • @capacitor/app: Gestiona los callbacks de enlaces profundos cuando Auth0 redirige a tu aplicación

   El plugin Browser de Capacitor en iOS usa SFSafariViewController, que en iOS 11+ no comparte cookies con Safari en el dispositivo. Esto significa que SSO no funcionará en esos dispositivos. Si necesitas SSO, usa un plugin compatible que utilice ASWebAuthenticationSession.

3. Configura tu aplicación de Auth0

   A continuación, debes crear una nueva aplicación en tu tenant de Auth0 y agregar las variables de entorno a tu proyecto.

   Tienes tres opciones para configurar tu aplicación de Auth0: usar la herramienta Quick Setup (recomendado), ejecutar un comando de CLI o configurar manualmente a través del Dashboard.

   A lo largo de este inicio rápido, YOUR_PACKAGE_ID es el ID de paquete de su aplicación. Este corresponde al campo appId en su archivo capacitor.config.ts (por ejemplo, io.ionic.starter). Consulte el esquema de configuración de Capacitor para obtener más información.

   Configuración rápida (recomendada)

   Cree una aplicación en Auth0 y copie el archivo .env rellenado previamente con los valores de configuración correctos.

   Después de crear la aplicación, vaya a Settings en el Auth0 Dashboard y actualice Allowed Callback URLs y Allowed Logout URLs para sustituir YOUR_PACKAGE_ID por su ID de paquete real y YOUR_AUTH0_DOMAIN por su dominio de Auth0:

   YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
   

   Asegúrate también de que Application Type esté configurado como Native y de que Token Endpoint Authentication Method esté configurado como None.

   CLI

   Ejecute el siguiente comando en el directorio raíz de su proyecto para crear una aplicación de Auth0 y generar un archivo .env:

   Mac

   # Instale Auth0 CLI (si todavía no está instalado)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Cree una aplicación nativa de Auth0
   auth0 apps create \
     --name "Ionic React App" \
     --type native \
     --callbacks "YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback" \
     --logout-urls "YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback" \
     --origins "capacitor://localhost,http://localhost"
   

   Este comando hará lo siguiente:

   1. Comprobar si está autenticado (y pedirle que inicie sesión si es necesario)
   2. Crear una aplicación nativa de Auth0
   3. Mostrar el Dominio y el ID de cliente; copie estos valores en un archivo .env en la raíz de su proyecto

   Cree un archivo .env con los valores de la salida de la CLI:

   Dashboard

   Antes de empezar, crea un archivo .env en el directorio raíz de tu proyecto

   .env

   VITE_AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
   VITE_AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
   

   1. Ve al Auth0 Dashboard
   2. Haz clic en Applications > Applications > Create Application
   3. En la ventana emergente, introduce un nombre para tu aplicación, selecciona Native como tipo de aplicación y haz clic en Create
   4. Ve a la pestaña Settings en la página Application Details
   5. Reemplaza YOUR_AUTH0_APP_DOMAIN y YOUR_AUTH0_APP_CLIENT_ID en el archivo .env por los valores de dominio e ID de cliente del Dashboard
   6. Establece Token Endpoint Authentication Method en None

   Por último, en la pestaña Settings de la página Application Details, configura las siguientes URL (reemplaza YOUR_PACKAGE_ID por el valor de appId en capacitor.config.ts):

   Allowed Callback URLs:

   YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
   

   URL de cierre de sesión permitidas:

   YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
   

   Orígenes permitidos:

   capacitor://localhost, http://localhost
   

   Allowed Callback URLs son una medida de seguridad fundamental para garantizar que los usuarios vuelvan de forma segura a tu aplicación después de autenticarse. Sin una URL que coincida, el proceso de Login fallará y los usuarios verán una página de error de Auth0 en lugar de acceder a tu aplicación.

   Allowed Logout URLs son esenciales para ofrecer una experiencia fluida al cerrar sesión. Sin una URL que coincida, los usuarios no serán redirigidos de vuelta a tu aplicación después del Logout y, en su lugar, se quedarán en una página genérica de Auth0.

   Allowed Origins (capacitor://localhost para iOS y http://localhost para Android) son necesarias para que tu aplicación nativa pueda comunicarse con la API de Auth0.

   Verifica que exista tu archivo .env: cat .env (Mac/Linux) o type .env (Windows)

4. Configura el Auth0Provider

   Abre src/main.tsx y envuelve el componente App con Auth0Provider. Los ajustes específicos para móviles useRefreshTokens y useRefreshTokensFallback son obligatorios para las aplicaciones de Ionic en iOS y Android.

   src/main.tsx

   import React from 'react';
   import { createRoot } from 'react-dom/client';
   import App from './App';
   import { Auth0Provider } from '@auth0/auth0-react';
   
   // Debe coincidir con el appId en tu capacitor.config.ts
   const appId = 'io.ionic.starter';
   
   createRoot(document.getElementById('root')!).render(
     <React.StrictMode>
       <Auth0Provider
         domain={import.meta.env.VITE_AUTH0_DOMAIN}
         clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
         useRefreshTokens={true}
         useRefreshTokensFallback={false}
         authorizationParams={{
           redirect_uri: `${appId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${appId}/callback`
         }}
       >
         <App />
       </Auth0Provider>
     </React.StrictMode>
   );
   

   • useRefreshTokens: Obligatorio para Ionic en Android e iOS. Los navegadores móviles bloquean las cookies de terceros, por lo que el SDK usa tokens de actualización en lugar de autenticación silenciosa basada en iframe.
   • useRefreshTokensFallback: Debe ser false para evitar que el SDK intente usar autenticación silenciosa basada en iframe, ya que no está disponible en dispositivos móviles.
   • authorizationParams.redirect_uri: Usa el ID del paquete como esquema de URL personalizado para que el sistema operativo pueda dirigir el callback de Auth0 a tu aplicación.

   Para conservar la autenticación después de cerrar y volver a abrir la aplicación, quizá quieras establecer cacheLocation en localstorage, pero ten en cuenta los riesgos de almacenar tokens en localstorage. En Capacitor, localstorage debe tratarse como transitorio: el sistema operativo puede borrarlo inesperadamente. Consulta la guía de Capacitor sobre almacenamiento.

   Recomendamos no usar el plugin Preferences de Capacitor para almacenar tokens, ya que se basa en UserDefaults (iOS) y SharedPreferences (Android), que no están cifrados y podrían sincronizarse con la nube. El SDK admite implementaciones de caché personalizadas si necesitas un mecanismo de almacenamiento más seguro y persistente.

5. Crear los controladores de Login, Logout, Profile y callback

   Crear archivos

   Mac/Linux

   touch src/LoginButton.tsx && touch src/LogoutButton.tsx && touch src/Profile.tsx
   

   Y agrega los siguientes fragmentos de código

   El callback openUrl en LoginButton y LogoutButton utiliza el plugin Browser de Capacitor para abrir las páginas de Login y Logout de Auth0 en el componente de navegador del sistema del dispositivo, en lugar de abandonar la aplicación por completo.

   El componente App escucha el evento appUrlOpen, que se activa cuando Auth0 redirige a tu aplicación mediante el esquema de URL personalizado. Llama a handleRedirectCallback para intercambiar el código de autorización por tokens y, luego, cierra el navegador.

   De forma predeterminada, el método loginWithRedirect del SDK usa window.location.href para ir a la página de Login, lo que abre la aplicación de navegador predeterminada del dispositivo. Configurar openUrl para usar Browser.open mantiene el flujo de autenticación dentro del contexto de tu aplicación para ofrecer una mejor experiencia de usuario.

6. Ejecuta tu aplicación

   Primero, prueba en el navegador

   ionic serve
   

   Al ejecutar en el navegador con ionic serve, la redirección con el esquema de URL personalizado (io.ionic.starter://...) no funcionará porque los navegadores no admiten esquemas de URL personalizados. Para probar en el navegador, cambia temporalmente redirect_uri a http://localhost:8100 en src/main.tsx y agrega http://localhost:8100 a Allowed Callback URLs y Allowed Logout URLs en el Dashboard de tu aplicación de Auth0. Recuerda deshacer este cambio antes de compilar para nativo.

   Para ejecutar en un dispositivo o simulador, primero agrega las plataformas nativas:

   npx cap add ios
   npx cap add android
   

   Luego, compila, sincroniza y ejecuta:

   iOS

   ionic build && npx cap sync && npx cap run ios
   

   Debes agregar las plataformas nativas con npx cap add antes de poder ejecutarlas. Esto solo debe hacerse una vez por plataforma. Después, npx cap sync copia los recursos web compilados y actualiza los plugins nativos.

Punto de control

Ahora deberías tener un inicio de sesión de Auth0 completamente funcional en tu aplicación Ionic. Al ejecutarla en un dispositivo, al tocar “Iniciar sesión” se abre la página de Universal Login de Auth0 en el navegador del sistema y, después de autenticarte, se te redirige a tu aplicación, donde se muestra el perfil del usuario.

---

​

Uso avanzado

Configuración del esquema de URL personalizado (iOS y Android)

Para que los callbacks de Auth0 funcionen en dispositivos, registra el ID de tu paquete como un esquema de URL personalizado en cada plataforma.

iOS — agrega esto a ios/App/App/Info.plist:

ios/App/App/Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>io.ionic.starter</string>
    </array>
  </dict>
</array>

Android — agrega un filtro intent dentro de la <activity> principal en android/app/src/main/AndroidManifest.xml:

android/app/src/main/AndroidManifest.xml

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="io.ionic.starter" />
</intent-filter>

Reemplaza io.ionic.starter por el valor real de appId en capacitor.config.ts.

Para obtener más información, consulta Defining a Custom URL Scheme para iOS o Create Deep Links to App Content para Android.

Protección de rutas con Ionic Router

Usa el estado de autenticación de Auth0 para proteger rutas específicas en tu aplicación Ionic:

src/App.tsx

import { useAuth0, withAuthenticationRequired } from '@auth0/auth0-react';
import { IonReactRouter } from '@ionic/react-router';
import { IonRouterOutlet } from '@ionic/react';
import { Route, Redirect } from 'react-router-dom';
import HomePage from './pages/Home';
import DashboardPage from './pages/Dashboard';

const ProtectedRoute = ({ component, ...args }: any) => {
  const Component = withAuthenticationRequired(component, {
    onRedirecting: () => <div className="ion-padding">Loading...</div>,
  });
  return <Route {...args} render={() => <Component />} />;
};

const App: React.FC = () => {
  // ... manejador de callback del paso anterior

  return (
    <IonApp>
      <IonReactRouter>
        <IonRouterOutlet>
          <Route exact path="/home" component={HomePage} />
          <ProtectedRoute exact path="/dashboard" component={DashboardPage} />
          <Route exact path="/">
            <Redirect to="/home" />
          </Route>
        </IonRouterOutlet>
      </IonReactRouter>
    </IonApp>
  );
};

El HOC withAuthenticationRequired redirige automáticamente a los usuarios no autenticados a la página de Login de Auth0 cuando intentan acceder a una ruta protegida.

Llamadas a APIs protegidas

Configura tu Auth0Provider para incluir la audiencia de una API y usa el método getAccessTokenSilently para obtener tokens de acceso para tu backend:

src/main.tsx

<Auth0Provider
  domain={import.meta.env.VITE_AUTH0_DOMAIN}
  clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
  useRefreshTokens={true}
  useRefreshTokensFallback={false}
  authorizationParams={{
    redirect_uri: `${appId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${appId}/callback`,
    audience: "YOUR_API_IDENTIFIER"
  }}
>
  <App />
</Auth0Provider>

Luego, realiza llamadas autenticadas a la API desde tus componentes:

src/ApiCall.tsx

import { useState } from 'react';
import { useAuth0 } from '@auth0/auth0-react';
import { IonButton, IonText } from '@ionic/react';

const ApiCall: React.FC = () => {
  const { getAccessTokenSilently } = useAuth0();
  const [result, setResult] = useState<string | null>(null);

  const callApi = async () => {
    try {
      const token = await getAccessTokenSilently();

      const response = await fetch('https://your-api.example.com/protected', {
        headers: {
          Authorization: `Bearer ${token}`
        }
      });

      const data = await response.json();
      setResult(JSON.stringify(data, null, 2));
    } catch (error) {
      console.error('API call failed:', error);
    }
  };

  return (
    <div className="ion-padding">
      <IonButton onClick={callApi}>Call Protected API</IonButton>
      {result && (
        <IonText>
          <pre>{result}</pre>
        </IonText>
      )}
    </div>
  );
};

export default ApiCall;