Ajouter la connexion à votre application Ionic Vue avec Capacitor

Ce guide explique comment intégrer Auth0 à une application Ionic Vue avec Capacitor à l’aide du Auth0 Vue SDK.

Utilisez l’IA pour intégrer Auth0

Si vous utilisez un assistant IA de programmation comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter automatiquement l’authentification Auth0 en quelques minutes à l’aide d’agent skills. Commencez par installer les Auth0 agent skills :

npx skills add auth0/agent-skills --skill auth0

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my Ionic Vue app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les identifiants, installera le Auth0 Vue SDK et les plugins Capacitor, configurera les liens profonds et mettra en place les flux de connexion et de déconnexion avec l’intégration au navigateur natif. Pour en savoir plus, consultez Auth0 agent skills.

​

Pour commencer

Ce Quickstart explique comment ajouter l’authentification Auth0 à une application Ionic Vue exécutée sur iOS et Android avec Capacitor. Vous créerez une application mobile sécurisée avec des fonctionnalités de login, de logout et de profil utilisateur à l’aide de l’Auth0 Vue SDK et des plugins de navigateur natifs de Capacitor.

1. Créer un nouveau projet

   Créer un nouveau projet Ionic Vue avec Capacitor

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

   Ouvrez le projet

   cd auth0-ionic-vue
   

   Assurez-vous d’utiliser le paquet @ionic/cli (et non le paquet ionic, qui est obsolète). Si vous voyez des erreurs liées à --npm-client pendant la création du projet, mettez votre CLI à jour :

   npm uninstall -g ionic
   npm i -g @ionic/cli
   
2. Installez le SDK Auth0 Vue et les plugiciels de Capacitor

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

   @capacitor/browser ouvre la page Auth0 Universal Login dans le navigateur système de l’appareil (SFSafariViewController sur iOS, Chrome Custom Tabs sur Android) pour une authentification sécurisée.

   @capacitor/app écoute les événements de lien profond afin que votre application puisse gérer le callback OAuth lorsque Auth0 redirige l’utilisateur après la connexion.

3. Configurez votre Auth0 App

   Ensuite, vous devez créer une nouvelle application dans votre tenant Auth0. Les applications Ionic Capacitor utilisent le type d’application Native avec des URL de callback utilisant un schéma d’URL personnalisé.

   Vous avez trois options pour configurer votre application Auth0 : utiliser l’outil Quick Setup (recommandé), exécuter une commande CLI ou faire la configuration manuellement dans le Dashboard :

   Configuration rapide (recommandée)

   Créez une application Auth0 Native et obtenez vos identifiants.

   Après avoir créé votre application, notez les valeurs Domain et Client ID pour l’étape suivante.

   Vous devrez aussi configurer les URL de callback et de logout dans le Dashboard. Consultez la configuration des URL ci-dessous.

   CLI

   Exécutez les commandes suivantes dans le répertoire racine de votre projet pour créer une application Auth0 :

   Mac

   # Installer Auth0 CLI (si ce n’est pas déjà fait)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Configurer l’application Auth0 et générer le fichier .env
   auth0 qs setup --app --type native --framework ionic-vue --build-tool vite --name "My Ionic Vue App"
   

   Cette commande va :

   1. Vérifier si vous êtes authentifié (et vous inviter à vous connecter au besoin)
   2. Créer une application Auth0 Native
   3. Générer un fichier .env contenant votre domaine Auth0 et votre ID client

   Dashboard

   1. Accédez au Auth0 Dashboard
   2. Cliquez sur Applications > Applications > Create Application
   3. Entrez un nom pour votre application (par exemple, Ionic Vue App), sélectionnez Native comme type d’application, puis cliquez sur Create
   4. Passez à l’onglet Settings et notez vos valeurs Domain et Client ID

   Dans ce guide, YOUR_PACKAGE_ID correspond à l’ID du package de votre application. Vous pouvez le trouver et le configurer dans le champ appId de votre fichier capacitor.config.ts. Consultez le schéma de configuration de Capacitor pour plus d’info.

   Configurez les URL suivantes dans l’onglet Settings de la page Details de votre Application :

   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
   

   Les Allowed Callback URLs constituent une mesure de sécurité essentielle pour garantir que les utilisateurs sont redirigés de façon sécuritaire vers votre application après l’authentication. Sans URL correspondante, le processus de connexion échouera et les utilisateurs seront bloqués sur une page d’erreur Auth0 au lieu d’accéder à votre application.

   Les Allowed Logout URLs sont essentielles pour offrir une expérience fluide au moment de la déconnexion. Sans URL correspondante, les utilisateurs ne seront pas redirigés vers votre application après le logout et resteront plutôt sur une page Auth0 générique.

   Les Allowed Origins doivent inclure capacitor://localhost (iOS) et http://localhost (Android) pour les requêtes d’application native vers Auth0.

   Si vous avez utilisé Quick Setup ou CLI, accédez à l’onglet Settings de votre application dans le Auth0 Dashboard pour configurer les URL de callback et de logout indiquées dans l’onglet Dashboard ci-dessus.

4. Configurer le plugin 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'
   
   // Créer l’URL de rappel à partir de l’ID du paquet de votre application
   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 — Les navigateurs mobiles bloquent les cookies tiers, donc l’authentification silencieuse basée sur un iframe ne fonctionne pas. Les jetons d’actualisation appellent directement le point de terminaison /oauth/token.
   • useRefreshTokensFallback: false — Empêche le SDK de tenter la solution de secours basée sur un iframe, qui n’est pas offerte sur mobile.
   • router.isReady().then(...) — Garantit que Vue Router est entièrement initialisé avant que le SDK traite le callback OAuth, ce qui évite les conflits de synchronisation.

   Pour conserver l’authentification après avoir fermé puis rouvert l’application, vous pouvez définir cacheLocation sur localstorage, mais sachez qu’il y a des risques à stocker des jetons dans localstorage. De plus, localstorage doit être considéré comme temporaire dans les applications Capacitor, car les données pourraient être récupérées de manière inattendue. Consultez aussi les recommandations sur le stockage dans la documentation de Capacitor.

5. Créer des composants d’authentification

   Créer des fichiers de composants

   Mac/Linux

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

   Ajoutez le code suivant aux nouveaux composants, puis mettez à jour les fichiers App.vue et HomePage.vue existants

6. Lancez votre application

   Commencez par tester dans le navigateur :

   ionic serve
   

   Lorsque vous exécutez l’application dans le navigateur avec ionic serve, la redirection à l’aide d’un schéma d’URL personnalisé ne fonctionnera pas, car les navigateurs ne prennent pas en charge les schémas d’URL personnalisés. Pour faire des tests dans le navigateur, remplacez temporairement redirect_uri par http://localhost:8100 dans src/main.ts, puis ajoutez http://localhost:8100 à Allowed Callback URLs et à Allowed Logout URLs de votre application Auth0 dans le Dashboard. N’oubliez pas de rétablir cette modification avant de générer l’application native.

   Pour exécuter l’application sur un appareil ou dans un simulateur, ajoutez d’abord les plateformes natives :

   npx cap add ios
   npx cap add android
   

   Ensuite, compilez, synchronisez et exécutez :

   iOS

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

   Vous devez ajouter les plateformes natives avec npx cap add avant de pouvoir les exécuter. Cette opération ne doit être effectuée qu’une seule fois par plateforme. Assurez-vous d’abord d’avoir enregistré le schéma d’URL personnalisé pour votre plateforme.

Vérification

Vous devriez maintenant avoir une expérience de connexion Auth0 entièrement fonctionnelle dans votre application Ionic Vue, avec la connexion, la déconnexion et les renseignements du profil utilisateur.

---

​

Utilisation avancée

Configuration d’un schéma d’URL personnalisé

Enregistrez le schéma d’URL personnalisé de votre application afin que le système d’exploitation puisse rediriger l’URL de rappel OAuth vers votre application après l’authentification.

​

iOS

Enregistrez votre schéma d’URL personnalisé dans votre ios/App/App/Info.plist :

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

Remplacez YOUR_PACKAGE_ID par le appId de votre capacitor.config.ts. Pour en savoir plus, consultez Defining a Custom URL Scheme.

​

Android

Ajoutez un filtre d’intention dans votre android/app/src/main/AndroidManifest.xml, à l’intérieur de la balise principale <activity> :

<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>

Pour en savoir plus, consultez Create Deep Links to App Content.

Après avoir modifié les fichiers du projet natif, exécutez npx cap sync pour vous assurer que vos changements sont appliqués.

Protection des routes avec Vue Router

Utilisez le authGuard intégré de l’Auth0 Vue SDK pour protéger les routes qui nécessitent une authentification :

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

Le authGuard redirige automatiquement les utilisateurs non authentifiés vers la page Auth0 Universal Login. Après la connexion, ils sont renvoyés vers la route initialement demandée.

Appeler des API protégées

Configurez le paramètre audience dans votre configuration createAuth0 pour demander des jetons d’accès pour votre API :

src/main.ts

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

Utilisez ensuite getAccessTokenSilently dans vos composants pour récupérer des jetons et effectuer des appels d’API authentifiés :

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>

La méthode getAccessTokenSilently récupère le jeton depuis le cache ou l’actualise automatiquement au moyen du jeton d’actualisation, au besoin.

Utilisation du modèle defineComponent

Si vous préférez le modèle explicite defineComponent à <script setup>, voici à quoi ressemble le composant LoginButton avec cette approche :

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>

Le modèle defineComponent exige d’enregistrer explicitement les composants enfants et de retourner les valeurs depuis la fonction setup(). Les deux modèles sont entièrement pris en charge par le Auth0 Vue SDK.

Problèmes courants et solutions

​

Erreur de non-correspondance de l’URL de rappel

Solution : Vérifiez que l’URL de rappel dans votre Auth0 Dashboard correspond exactement à l’URL construite dans votre application. Assurez-vous que YOUR_PACKAGE_ID correspond au champ appId dans votre fichier capacitor.config.ts.

​

Erreur « PKCE not allowed »

Correctif :

1. Accédez à Auth0 Dashboard > Applications > Your Application
2. Remplacez Application Type par Native
3. Définissez Token Endpoint Authentication Method sur None
4. Enregistrez les modifications et réessayez

​

SSO ne fonctionne pas sur iOS

Le Plugin Browser de Capacitor utilise SFSafariViewController, qui ne partage pas les cookie avec Safari sur iOS 11+. Si vous avez besoin du SSO, utilisez un Plugin compatible qui repose sur ASWebAuthenticationSession.

​

Le login fonctionne, mais l’utilisateur reste non authentifié après le redémarrage de l’application

Activez cacheLocation: 'localstorage' dans la configuration createAuth0 pour enregistrer les jetons entre les redémarrages de l’application. Gardez à l’esprit les implications de sécurité. Le SDK prend aussi en charge des implémentations de cache personnalisées pour un stockage plus sécurisé.

​

Le navigateur ne se ferme pas après le login

Assurez-vous d’appeler Browser.close() dans l’écouteur de l’événement appUrlOpen de votre composant App.vue. Sur Android, Browser.close() est un no-op; le navigateur se ferme donc automatiquement.

​

La page de connexion s’ouvre dans l’application de navigateur par défaut de l’appareil

Si la page de connexion s’ouvre dans Safari ou Chrome au lieu d’un navigateur intégré à l’application, assurez-vous de transmettre le callback openUrl à loginWithRedirect et à logout. Sinon, le SDK utilise window.location.href par défaut, ce qui redirige l’application au complet.