Ajouter la fonctionnalité Login à votre application Ionic Vue avec Capacitor

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

Utiliser l’IA pour intégrer Auth0

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

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

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 SDK Auth0 Vue et les plugins Capacitor, configurera les liens profonds et mettra en œuvre des flux de connexion et de déconnexion avec intégration au navigateur natif. Pour en savoir plus, consultez Auth0 agent skills.

​

Pour commencer

Ce guide de démarrage rapide montre 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 connexion, de déconnexion et de profil utilisateur à l’aide du SDK Auth0 pour Vue et des plugiciels de navigateur natifs de Capacitor.

1. Créer un nouveau projet

   Créez un 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 package @ionic/cli (et non le package ionic, maintenant obsolète). Si des erreurs liées à --npm-client s’affichent pendant la création du projet, mettez à jour votre CLI :

   npm uninstall -g ionic
   npm i -g @ionic/cli
   
2. Installez le SDK Vue d’Auth0 et les plugins Capacitor

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

   @capacitor/browser ouvre la page Universal Login d’Auth0 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 la redirection OAuth lorsqu’Auth0 redirige l’utilisateur après la connexion.

3. Configurez votre application Auth0

   La prochaine étape consiste à créer une nouvelle application dans votre locataire Auth0. Les applications Ionic Capacitor utilisent le type d’application Native avec des URL de rappel basées sur un schéma d’URL personnalisé.

   Vous avez trois options pour configurer votre application Auth0 : utiliser l’outil de configuration rapide (recommandé), exécuter une commande CLI ou effectuer la configuration manuellement dans l’Auth0 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 rappel et de déconnexion dans le Dashboard. Consultez la configuration des URL ci-dessous.

   CLI

   Exécutez les commandes suivantes à la 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
   
   # Ouvrir une session et créer une application Native
   auth0 login && auth0 apps create \
     -n "My Ionic Vue App" \
     -t native \
     -o "capacitor://localhost,http://localhost" \
     --no-input
   

   Cette commande va :

   1. Vous authentifier auprès d’Auth0 (et vous inviter à ouvrir une session au besoin)
   2. Créer une application Native avec les origines autorisées configurées
   3. Afficher les valeurs Domain et Client ID à utiliser dans votre projet

   Vous devrez tout de même configurer les URL de rappel et de déconnexion dans le Dashboard. Voir ci-dessous.

   Dashboard

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

   Dans ce guide, YOUR_PACKAGE_ID correspond à l’ID de 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 en savoir plus.

   Configurez les URL suivantes dans l’onglet Settings de la page des détails 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
   

   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’authentification. Sans URL correspondante, le processus de connexion échouera et les utilisateurs verront une page d’erreur Auth0 au lieu d’accéder à votre application.

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

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

   Si vous avez utilisé la Configuration rapide ou le CLI, ouvrez l’onglet Settings de votre application dans l’Auth0 Dashboard pour configurer les URL de rappel et de déconnexion indiquées dans l’onglet Dashboard ci-dessus.

4. Configurer le plugiciel 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'
   
   // Construire l'URL de callback à partir de l'identifiant de 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; l’authentification silencieuse basée sur des iframes ne fonctionne donc pas. Les jetons d’actualisation appellent directement le point de terminaison /oauth/token.
   • useRefreshTokensFallback: false — Empêche le SDK de tenter le mécanisme de repli basé sur une iframe, qui n’est pas disponible sur mobile.
   • router.isReady().then(...) — Garantit que Vue Router est entièrement initialisé avant que le SDK ne traite le callback OAuth, ce qui évite les conditions de concurrence.

   Pour conserver l’authentification après la fermeture et la réouverture de l’application, vous pouvez définir cacheLocation à localstorage, mais veuillez prendre connaissance des risques liés au stockage des jetons dans localstorage. De plus, localstorage doit être considéré comme transitoire dans les applications Capacitor, car les données pourraient être récupérées de façon inattendue. Veuillez consulter les directives 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 et mettez à jour les fichiers App.vue et HomePage.vue existants

6. Lancez votre application

   Commencez par tester dans le navigateur :

   ionic serve
   

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

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

   npx cap add ios
   npx cap add android
   

   Ensuite, générez, 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.

Point de contrôle

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

---

​

Utilisation avancée

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

Enregistrez le schéma d’URL personnalisé de votre application pour 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 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 fichier capacitor.config.ts. Pour en savoir plus, consultez Defining a Custom URL Scheme.

​

Android

Ajoutez un filtre d’intent à 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 pris en compte.

Protection des routes avec Vue Router

Utilisez le authGuard intégré du SDK Auth0 Vue 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 Universal Login d’Auth0. Après la connexion, ils sont redirigés vers la route demandée au départ.

Appel d’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 à partir de la fonction setup(). Les deux modèles sont entièrement pris en charge par le SDK Auth0 Vue.

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 de votre capacitor.config.ts.

​

Erreur « PKCE not allowed »

Correctif :

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

​

Le SSO ne fonctionne pas sur iOS

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

​

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

Activez cacheLocation: 'localstorage' dans la configuration createAuth0 pour conserver les jetons d’une ouverture de l’application à l’autre. Tenez compte des 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 la connexion

Assurez-vous d’appeler Browser.close() dans l’écouteur d’événement appUrlOpen de votre composant App.vue. Sur Android, Browser.close() n’a aucun effet; 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’une fenêtre de navigateur intégrée à l’application, assurez-vous de transmettre le callback openUrl à loginWithRedirect et à logout. Sinon, le SDK utilise par défaut window.location.href, ce qui redirige l’ensemble de l’application.