Agrega Login a tu aplicación Ionic Vue con Capacitor

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

Usa 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 minutos con agent skills. Primero, instala las agent skills de Auth0:

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

Luego, pídele a tu asistente de IA:

Add Auth0 authentication to my Ionic Vue app

Tu asistente de IA creará automáticamente tu aplicación de Auth0, obtendrá las credenciales, instalará el SDK de Auth0 para Vue 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 las agent skills de Auth0.

​

Primeros pasos

Este inicio rápido muestra cómo añadir la autenticación de Auth0 a una aplicación Ionic Vue que se ejecuta en iOS y Android con Capacitor. Crearás una aplicación móvil segura con funciones de Login, cierre de sesión y perfil de usuario mediante el SDK de Auth0 para Vue y los complementos de navegador nativos de Capacitor.

1. Crear un proyecto nuevo

   Crea un nuevo proyecto de Ionic Vue con Capacitor

   npx ionic start auth0-ionic-vue blank --type=vue --capacitor
   

   Abre el proyecto

   cd auth0-ionic-vue
   

   Asegúrate de usar el paquete @ionic/cli (no el paquete ionic, que está obsoleto). Si ves errores relacionados con --npm-client durante la creación del proyecto, actualiza tu CLI:

   npm uninstall -g ionic
   npm i -g @ionic/cli
   
2. Instala el SDK de Auth0 para Vue y los complementos de Capacitor

   npm install @auth0/auth0-vue @capacitor/browser @capacitor/app
   

   @capacitor/browser abre la página de Universal Login de Auth0 en el navegador del sistema del dispositivo (SFSafariViewController en iOS, Chrome Custom Tabs en Android) para proporcionar una autenticación segura.

   @capacitor/app detecta eventos de enlaces profundos para que tu aplicación pueda gestionar el callback de OAuth cuando Auth0 redirige de vuelta tras el Login.

3. Configura tu aplicación de Auth0

   A continuación, debes crear una nueva aplicación en tu inquilino de Auth0. Las aplicaciones Ionic Capacitor usan el tipo de aplicación Native con callbacks de esquema de URL personalizado.

   Tienes tres opciones para configurar tu aplicación de Auth0: usar la herramienta Quick Setup (recomendado), ejecutar un comando de la CLI o configurarla manualmente en el Dashboard:

   Quick Setup (recomendado)

   Crea una aplicación Native de Auth0 y obtén tus credenciales.

   Después de crear tu aplicación, anota los valores de dominio e ID de cliente para el siguiente paso.

   También tendrás que configurar las URL de callback y cierre de sesión en el Dashboard. Consulta la configuración de las URL a continuación.

   CLI

   Ejecuta los siguientes comandos en el directorio raíz de tu proyecto para crear una aplicación de Auth0:

   Mac

   # Instala Auth0 CLI (si aún no está instalado)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Inicia sesión y crea una aplicación Native
   auth0 login && auth0 apps create \
     -n "My Ionic Vue App" \
     -t native \
     -o "capacitor://localhost,http://localhost" \
     --no-input
   

   Este comando hará lo siguiente:

   1. Te autenticará en Auth0 (y te pedirá que inicies sesión si es necesario)
   2. Creará una aplicación Native con los orígenes permitidos configurados
   3. Mostrará el dominio y el ID de cliente para usarlos en tu proyecto

   Aún tendrás que configurar las URL de callback y cierre de sesión en el Dashboard. Consulta la información a continuación.

   Dashboard

   1. Ve al Auth0 Dashboard
   2. Haz clic en Applications > Applications > Create Application
   3. Introduce un nombre para tu aplicación (por ejemplo, Ionic Vue App), selecciona Native como tipo de aplicación y haz clic en Create
   4. Ve a la pestaña Settings y anota los valores de dominio e ID de cliente

   A lo largo de esta guía, YOUR_PACKAGE_ID es el ID de paquete de tu aplicación. Puedes encontrarlo y configurarlo en el campo appId de tu archivo capacitor.config.ts. Consulta el esquema de configuración de Capacitor para obtener más información.

   Configura las siguientes URL en la pestaña Settings de la página de detalles de tu aplicación:

   Allowed Callback URLs:

   YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback
   

   Allowed Logout URLs:

   YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback
   

   Allowed Origins:

   capacitor://localhost, http://localhost
   

   Allowed Callback URLs son una medida de seguridad fundamental para garantizar que los usuarios regresen de forma segura a tu aplicación después de autenticarse. Sin una URL coincidente, el proceso de inicio de sesión 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 coincidente, los usuarios no serán redirigidos de vuelta a tu aplicación después de cerrar sesión y, en su lugar, se quedarán en una página genérica de Auth0.

   Allowed Origins deben incluir capacitor://localhost (iOS) y http://localhost (Android) para las solicitudes de aplicaciones nativas a Auth0.

   Si usaste Quick Setup o CLI, ve a la pestaña Settings de tu aplicación en el Auth0 Dashboard para configurar las URL de callback y cierre de sesión que se muestran en la pestaña Dashboard anterior.

4. Configura el plugin de Auth0

   src/main.ts

   import { createApp } from 'vue'
   import App from './App.vue'
   import router from './router'
   import { IonicVue } from '@ionic/vue'
   import { createAuth0 } from '@auth0/auth0-vue'
   import config from '../capacitor.config'
   
   // Construye la URL de callback usando el ID de paquete de tu aplicación
   const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`
   
   const app = createApp(App)
     .use(IonicVue)
     .use(router)
   
   app.use(
     createAuth0({
       domain: '{yourDomain}',
       clientId: '{yourClientId}',
       useRefreshTokens: true,
       useRefreshTokensFallback: false,
       authorizationParams: {
         redirect_uri,
       },
     })
   )
   
   router.isReady().then(() => {
     app.mount('#app')
   })
   

   • useRefreshTokens: true — Los navegadores móviles bloquean las cookies de terceros, por lo que la autenticación silenciosa basada en iframe no funciona. Los Tokens de actualización usan directamente el endpoint /oauth/token.
   • useRefreshTokensFallback: false — Evita que el SDK intente usar la alternativa basada en iframe, que no está disponible en dispositivos móviles.
   • router.isReady().then(...) — Garantiza que Vue Router esté completamente inicializado antes de que el SDK procese el callback de OAuth, lo que evita condiciones de carrera.

   Para mantener 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. Además, localstorage debe tratarse como transitorio en las aplicaciones de Capacitor, ya que los datos podrían recuperarse inesperadamente. Lee la guía sobre almacenamiento en la documentación de Capacitor.

5. Crear componentes de autenticación

   Crear archivos de componentes

   Mac/Linux

   mkdir -p src/components && touch src/components/LoginButton.vue && touch src/components/LogoutButton.vue && touch src/components/UserProfile.vue
   

   Agrega el siguiente código a los nuevos componentes y actualiza los archivos App.vue y HomePage.vue existentes

6. Ejecute la aplicación

   Primero, haga la prueba en el navegador:

   ionic serve
   

   Cuando se ejecuta en el navegador con ionic serve, la redirección mediante un esquema de URL personalizado no funcionará, porque los navegadores no admiten esquemas de URL personalizados. Para hacer pruebas en el navegador, cambia temporalmente redirect_uri a http://localhost:8100 en src/main.ts y agrega http://localhost:8100 a Allowed Callback URLs y Allowed Logout URLs de tu aplicación de Auth0 en el Dashboard. Recuerda revertir este cambio antes de compilar para nativo.

   Para ejecutarlo 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. Solo es necesario hacerlo una vez por plataforma. Asegúrate primero de haber registrado el esquema de URL personalizado para tu plataforma.

Punto de control

Ahora debería tener una experiencia de Login de Auth0 totalmente funcional en su aplicación Ionic Vue, con Login, cierre de sesión e información del perfil de usuario.

---

​

Uso avanzado

Configuración de esquemas de URL personalizados

Registre el esquema de URL personalizado de su aplicación para que el sistema operativo pueda redirigir el callback de OAuth de vuelta a su aplicación tras la autenticación.

​

iOS

Registre el esquema de URL personalizado en ios/App/App/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_PACKAGE_ID</string>
    </array>
  </dict>
</array>

Sustituya YOUR_PACKAGE_ID por el appId de capacitor.config.ts. Para obtener más información, consulte Defining a Custom URL Scheme.

​

Android

Agregue un filtro de intents a android/app/src/main/AndroidManifest.xml, dentro de la etiqueta <activity> principal:

<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="YOUR_PACKAGE_ID" />
</intent-filter>

Para obtener más información, consulte Create Deep Links to App Content.

Después de modificar archivos del proyecto nativo, ejecute npx cap sync para asegurarse de que los cambios se apliquen.

Protección de rutas con Vue Router

Use el authGuard integrado del SDK de Auth0 para Vue para proteger las rutas que requieren autenticación:

src/router/index.ts

import { createRouter, createWebHistory } from '@ionic/vue-router'
import { authGuard } from '@auth0/auth0-vue'
import HomePage from '../views/HomePage.vue'
import ProfilePage from '../views/ProfilePage.vue'

const routes = [
  {
    path: '/',
    name: 'Home',
    component: HomePage,
  },
  {
    path: '/profile',
    name: 'Profile',
    component: ProfilePage,
    beforeEnter: authGuard,
  },
]

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
})

export default router

authGuard redirige automáticamente a los usuarios no autenticados a la página de Universal Login de Auth0. Después de iniciar sesión, vuelven a la ruta solicitada originalmente.

Llamada a API protegidas

Configure el parámetro audience en la configuración de createAuth0 para solicitar tokens de acceso para su API:

src/main.ts

app.use(
  createAuth0({
    domain: '{yourDomain}',
    clientId: '{yourClientId}',
    useRefreshTokens: true,
    useRefreshTokensFallback: false,
    authorizationParams: {
      redirect_uri,
      audience: 'YOUR_API_IDENTIFIER',
    },
  })
)

Luego, use getAccessTokenSilently en sus componentes para recuperar tokens y realizar llamadas autenticadas a la API:

src/components/ApiCall.vue

<template>
  <ion-button @click="callApi" :disabled="loading">
    {{ loading ? 'Calling...' : 'Call Protected API' }}
  </ion-button>
  <pre v-if="response">{{ JSON.stringify(response, null, 2) }}</pre>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useAuth0 } from '@auth0/auth0-vue'
import { IonButton } from '@ionic/vue'

const { getAccessTokenSilently } = useAuth0()
const response = ref(null)
const loading = ref(false)

const callApi = async () => {
  try {
    loading.value = true
    const token = await getAccessTokenSilently()

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

    response.value = await res.json()
  } catch (error) {
    console.error('API call failed:', error)
  } finally {
    loading.value = false
  }
}
</script>

El método getAccessTokenSilently recupera el token de la caché o lo renueva automáticamente mediante el token de actualización cuando sea necesario.

Uso del patrón defineComponent

Si prefieres el patrón explícito defineComponent en lugar de <script setup>, así es como se ve el componente LoginButton con este enfoque:

src/components/LoginButton.vue

<template>
  <ion-button @click="login" expand="block">Log in</ion-button>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import { useAuth0 } from '@auth0/auth0-vue'
import { Browser } from '@capacitor/browser'
import { IonButton } from '@ionic/vue'

export default defineComponent({
  components: { IonButton },
  setup() {
    const { loginWithRedirect } = useAuth0()

    const login = async () => {
      await loginWithRedirect({
        openUrl: (url: string) =>
          Browser.open({ url, windowName: '_self' }),
      })
    }

    return { login }
  },
})
</script>

El patrón defineComponent requiere registrar explícitamente los componentes hijo y devolver los valores desde la función setup(). Ambos patrones son totalmente compatibles con el SDK de Auth0 para Vue.

Problemas comunes y soluciones

​

Error de URL de callback no coincidente

Solución: Verifica que la URL de callback en tu Auth0 Dashboard coincida exactamente con la URL construida en tu aplicación. Asegúrate de que YOUR_PACKAGE_ID coincida con el campo appId en tu capacitor.config.ts.

​

Error “PKCE not allowed”

Solución:

1. Ve a Auth0 Dashboard > Applications > Your Application
2. Cambia Application Type a Native
3. Establece Token Endpoint Authentication Method en None
4. Guarda los cambios y vuelve a intentarlo

​

SSO no funciona en iOS

El plugin Browser de Capacitor usa SFSafariViewController, que no comparte cookies con Safari en iOS 11+. Si necesitas SSO, usa un plugin compatible que utilice ASWebAuthenticationSession.

​

Login funciona, pero el usuario sigue sin autenticarse después de reiniciar la aplicación

Habilita cacheLocation: 'localstorage' en la configuración de createAuth0 para conservar los tokens entre reinicios de la aplicación. Ten en cuenta las implicaciones de seguridad. El SDK también admite implementaciones de caché personalizadas para un almacenamiento más seguro.

​

El navegador no se cierra después del login

Asegúrate de llamar a Browser.close() dentro del listener del evento appUrlOpen en tu componente App.vue. En Android, Browser.close() no realiza ninguna acción, por lo que el navegador se cierra automáticamente.

​

La página de login se abre en la aplicación de navegador predeterminada del dispositivo

Si la página de login se abre en Safari o Chrome en lugar de un navegador integrado en la aplicación, asegúrate de pasar el callback openUrl a loginWithRedirect y logout. Sin él, el SDK usa window.location.href de forma predeterminada, lo que redirige toda la app fuera de la aplicación.