Intégration Auth0 Ionic Vue (Capacitor)

Ajoutez l'authentification Auth0 aux applications Ionic Vue utilisant Capacitor. Cette skill couvre l'authentification mobile native en utilisant le SDK @auth0/auth0-vue combiné aux plugins @capacitor/browser et @capacitor/app pour la gestion des deep links sur iOS et Android.

Agent instruction: Avant de fournir les instructions de configuration du SDK, récupérez la dernière version de release en exécutant :

gh api repos/auth0/auth0-vue/releases/latest --jq '.tag_name'

Utilisez la version retournée dans toutes les lignes de dépendances au lieu de toute version codée en dur ci-dessous.

Prérequis

• Node.js 18+
• Ionic CLI (npm install -g @ionic/cli)
• Une application Ionic Vue existante avec Capacitor configuré
• Compte et tenant Auth0
• Pour iOS : Xcode 14+ et CocoaPods
• Pour Android : Android Studio avec API level 21+
• Auth0 CLI — brew install auth0/auth0-cli/auth0

Quand NE PAS utiliser

Flux de démarrage rapide

Agent instruction: Suivez ces étapes dans l'ordre. Si le prompt de l'utilisateur fournit déjà les identifiants Auth0 (domain, client ID), utilisez-les directement — ignorez la configuration CLI. Quand les identifiants manquent, utilisez toujours l'Auth0 CLI pour créer l'application.

Agent instruction: Vérifiez si la codebase contient déjà un provider ou un wrapper d'auth existant. Recherchez les gestionnaires de login/logout existants, les boutons d'auth ou l'interface utilisateur liée à l'authentification à réutiliser. Si trouvés, intégrez Auth0 dans ces composants existants plutôt que d'en créer de nouveaux.

Étape 1 : Connexion Auth0 CLI et configuration de l'application

Agent instruction:

• Si les identifiants Auth0 (domain ET client ID) sont déjà dans le prompt de l'utilisateur: Utilisez-les directement et passez à l'étape 2.
• Si aucun identifiant n'est fourni: Suivez la configuration automatisée dans Setup Guide — Auth0 CLI Automated Setup pour :
  1. Vérifiez que l'Auth0 CLI est installé (installez si manquant).
  2. Vérifiez que l'utilisateur est connecté à l'Auth0 CLI (proposez d'exécuter auth0 login si nécessaire).
  3. Détectez le domain du tenant Auth0 actif.
  4. Lisez capacitor.config.ts pour obtenir l'ID de package de l'application.
  5. Créez une application Auth0 Native via auth0 apps create avec les bonnes callback URLs.
  6. Extrayez client_id et domain de la sortie CLI.
  7. Écrivez .env avec VITE_AUTH0_DOMAIN, VITE_AUTH0_CLIENT_ID et VITE_AUTH0_CALLBACK_URI.
  8. Mettez à jour src/main.ts pour lire les identifiants de import.meta.env.

N'INVITEZ PAS l'utilisateur à créer ou configurer manuellement une application Auth0. Utilisez toujours le chemin CLI.

Étape 2 : Installer les dépendances

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

Étape 3 : Configurer le plugin Auth0

Agent instruction: Si l'étape 1 a déjà écrit .env et mis à jour src/main.ts, vérifiez que la configuration semble correcte et passez à l'étape 4. Utilisez uniquement le template ci-dessous si vous configurez manuellement.

Enregistrez le plugin Auth0 Vue dans le point d'entrée de votre application (src/main.ts), en le configurant pour Capacitor. Les identifiants sont lus depuis .env via import.meta.env :

import { createApp } from 'vue';
import { createAuth0 } from '@auth0/auth0-vue';
import { IonicVue } from '@ionic/vue';
import App from './App.vue';
import router from './router';

// Agent: lisez appId depuis capacitor.config.ts et remplacez cette valeur
const packageId = "YOUR_PACKAGE_ID";

const app = createApp(App);

app.use(IonicVue);
app.use(router);
app.use(
  createAuth0({
    domain: import.meta.env.VITE_AUTH0_DOMAIN,
    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
    useRefreshTokens: true,
    useRefreshTokensFallback: false,
    authorizationParams: {
      redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
    }
  })
);

router.isReady().then(() => {
  app.mount('#app');
});

Étape 4 : Implémenter la connexion avec Capacitor Browser

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

const { loginWithRedirect } = useAuth0();

const login = async () => {
  await loginWithRedirect({
    async openUrl(url: string) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};
</script>

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

Étape 5 : Gérer le callback via Deep Link

Gérez le callback du deep link dans votre composant App.vue. Cela doit s'exécuter à l'initialisation de l'application :

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { useAuth0 } from '@auth0/auth0-vue';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { IonApp, IonRouterOutlet } from '@ionic/vue';

const { handleRedirectCallback } = useAuth0();

let urlOpenListener: { remove: () => void } | undefined;

onMounted(async () => {
  urlOpenListener = await CapApp.addListener('appUrlOpen', async ({ url }) => {
    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
      await handleRedirectCallback(url);
    }
    await Browser.close();
  });
});

onUnmounted(() => {
  urlOpenListener?.remove();
});
</script>

<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

Étape 6 : Implémenter la déconnexion

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

const domain = import.meta.env.VITE_AUTH0_DOMAIN;
// Agent: lisez appId depuis capacitor.config.ts et remplacez cette valeur
const packageId = "YOUR_PACKAGE_ID";
const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;

const { logout } = useAuth0();

const doLogout = async () => {
  await logout({
    logoutParams: {
      returnTo: logoutUri
    },
    async openUrl(url: string) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};
</script>

<template>
  <ion-button @click="doLogout">Log out</ion-button>
</template>

Étape 7 : Compiler et tester

Agent instruction: Après l'intégration, vérifiez la compilation :

ionic build
npx cap sync

Pour iOS : npx cap open ios puis compilez dans Xcode. Pour Android : npx cap open android puis compilez dans Android Studio. Si la compilation échoue, itérez jusqu'à 5-6 fois pour corriger les problèmes. Si toujours en échec, utilisez AskUserQuestion pour demander de l'aide.

Documentation détaillée

• Setup Guide — Configuration automatisée Auth0 CLI (connexion, création d'application, injection de credentials), enregistrement du schéma URL Capacitor, gestion des secrets
• Integration Patterns — Login/logout avec Capacitor Browser, gestion du callback deep link, profil utilisateur, routes protégées, accès aux tokens, gestion des erreurs
• Testing & Reference — Référence API complète pour les options createAuth0, composable useAuth0, configuration des plugins Capacitor, liste de contrôle des tests, problèmes courants

Erreurs courantes

Méthode WebAuth

Ce SDK utilise Auth0 Universal Login (WebAuth) via le plugin Capacitor Browser. La méthode loginWithRedirect() ouvre le endpoint d'autorisation Auth0 dans un navigateur système (SFSafariViewController sur iOS, Chrome Custom Tabs sur Android). Après l'authentification, Auth0 redirige vers l'application en utilisant une callback URL native avec un schéma personnalisé : {packageId}://{domain}/capacitor/{packageId}/callback. Le plugin @capacitor/app capture ce deep link, et handleRedirectCallback(url) traite l'échange du code d'autorisation.

Contrairement aux SDKs natifs standard qui utilisent https://{domain}/android/{packageId}/callback ou https://{domain}/ios/{bundleId}/callback, les applications Ionic Capacitor utilisent le chemin de callback spécifique à Capacitor avec l'ID de package comme schéma URL.

Skills connexes

• auth0-vue — Vue SPA (navigateur uniquement, sans Capacitor)
• auth0-ionic-react — Ionic avec React et Capacitor
• auth0-ionic-angular — Ionic avec Angular et Capacitor
• auth0-react-native — React Native (CLI bare, sans Ionic/Capacitor)
• auth0-expo — Expo (React Native) avec Auth0

Référence rapide

Références

• Auth0 Ionic Vue Quickstart
• Auth0 Vue SDK GitHub
• Auth0 Vue SDK API Reference
• Ionic Vue Capacitor Sample App
• Capacitor Browser Plugin
• Capacitor App Plugin
• Auth0 Dashboard